OutcomeOS MCP Server

Connect AI assistants like Cursor to OutcomeOS for seamless task management, analytics, and workflow automation.

Quick Start

Get started in 30 seconds:

npx @outcomeos/mcp-server --help

What is This?

The OutcomeOS MCP Server is a Model Context Protocol server that connects AI assistants to OutcomeOS. It enables your AI assistant to:

• Read your tasks, outcomes, analytics, and team data
• Create and update tasks, lists, and outcomes
• Search across your productivity data with semantic AI
• Execute GraphQL queries for advanced data access
• Automate workflows with rules and check-ins

Add this to your Cursor settings and your AI assistant becomes OutcomeOS-powered! 🚀

{
  "mcpServers": {
    "OutcomeOS": {
      "command": "npx",
      "args": ["@outcomeos/mcp-server"],
      "env": {
        "OUTCOMEOS_API_KEY": "your_api_key_here"
      }
    }
  }
}

Features

🔧 15+ AI Tools

Create tasks, update outcomes, search with AI, execute GraphQL queries, manage workflows

📊 15+ Data Resources

Access tasks, analytics, team data, rules, check-ins, and more through your AI assistant

🚀 Advanced Capabilities

• Vector Search: Semantic content discovery across all entities
• GraphQL Integration: Type-safe queries with full schema access
• Workflow Automation: Rules engine and team check-ins
• Real-time Analytics: Performance metrics and insights
• Team Collaboration: Multi-team support with proper isolation

🎯 Enterprise Ready

• Authentication via API keys
• Team-scoped data access
• Type-safe implementation
• Comprehensive error handling

Installation & Setup

Option 1: NPX (Recommended)

No installation required! Just configure and run:

# Test it works
npx @outcomeos/mcp-server --version

# Get help
npx @outcomeos/mcp-server --help

Option 2: Global Install

npm install -g @outcomeos/mcp-server
outcomeos-mcp --version

Option 3: Local Development

git clone https://github.com/outcomeos/outcomeOS.git
cd outcomeOS/mcp
npm install
npm run dev

Configuration

Environment Variables

| Variable | Required | Description | Default | | -------------------- | -------- | ------------------------------ | -------------------------- | | OUTCOMEOS_API_KEY | ✅ | Your OutcomeOS API key | - | | OUTCOMEOS_TEAM_ID | ❌ | Default team ID for operations | Auto-detect | | OUTCOMEOS_BASE_URL | ❌ | OutcomeOS instance URL | https://app.outcomeos.io |

Getting Your API Key

1. Login to OutcomeOS
2. Go to Settings → Integrations
3. Generate a new API Key
4. Copy the key (starts with ok_)

Usage Examples

Basic Usage

export OUTCOMEOS_API_KEY="ok_your_api_key_here"
npx @outcomeos/mcp-server

With Team Context

export OUTCOMEOS_TEAM_ID="your-team-uuid"
npx @outcomeos/mcp-server --version

Custom Instance

export OUTCOMEOS_BASE_URL="https://custom.outcomeos.io"
npx @outcomeos/mcp-server

Cursor Integration

Setup Steps

1. Get your API key from OutcomeOS Settings → Integrations
2. Add to Cursor settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "OutcomeOS": {
      "command": "npx",
      "args": ["@outcomeos/mcp-server"],
      "env": {
        "OUTCOMEOS_API_KEY": "ok_your_api_key_here",
        "OUTCOMEOS_TEAM_ID": "optional-team-uuid"
      }
    }
  }
}

3. Restart Cursor
4. Test it: Ask your AI assistant to "create a task" or "show my analytics"

Advanced Configuration

For teams with multiple OutcomeOS instances:

{
  "mcpServers": {
    "OutcomeOS-Production": {
      "command": "npx",
      "args": ["@outcomeos/mcp-server"],
      "env": {
        "OUTCOMEOS_API_KEY": "ok_prod_key",
        "OUTCOMEOS_BASE_URL": "https://app.outcomeos.io"
      }
    },
    "OutcomeOS-Staging": {
      "command": "npx",
      "args": ["@outcomeos/mcp-server"],
      "env": {
        "OUTCOMEOS_API_KEY": "ok_staging_key",
        "OUTCOMEOS_BASE_URL": "https://staging.outcomeos.io"
      }
    }
  }
}

Available Tools & Resources

🔧 Tools (Actions)

• create-task - Create new tasks (supports dependencies)
• update-task - Modify existing tasks (supports dependency updates)
• search-tasks - Find tasks with filters (dependency filtering)
• create-task-dependency - Create task dependencies
• remove-task-dependency - Remove task dependencies
• get-task-dependencies - Get task dependency information
• get-blocked-tasks - Find tasks blocked by dependencies
• create-list - Create projects/backlogs
• update-list - Modify lists
• search-lists - Find lists with filters
• create-outcome - Create new outcomes
• update-outcome - Modify outcomes
• create-key-result - Create key results
• update-key-result - Modify key results
• get-analytics - Retrieve performance metrics
• semantic-search - AI-powered content discovery
• graphql-query - Execute GraphQL queries
• add-comment - Add comments to entities

📊 Resources (Data Access)

• tasks - All tasks with metadata (includes dependency data)
• tasks/active - Currently active tasks
• tasks/overdue - Overdue tasks requiring attention
• tasks/blocked - Tasks blocked by dependencies
• tasks/blocking - Tasks blocking other tasks
• task-dependencies - Task dependency relationships
• lists - Projects, backlogs, templates
• lists/projects - Project lists only
• outcomes - Goals and objectives
• key-results - Measurable outcomes
• analytics/overview - High-level performance metrics
• analytics/tasks - Task-specific analytics
• activity/recent - Latest updates and changes
• users - Team members and assignments
• teams - Team information and structure
• statuses - Workflow statuses
• rules - Automation rules
• check-ins - Team check-ins and responses

Task Dependencies

The MCP server supports comprehensive task dependency management:

Creating Dependencies

// Create a task dependency (Task A blocks Task B)
await mcp.callTool("create-task-dependency", {
  blocking_task_id: "task-a-uuid",
  waiting_task_id: "task-b-uuid",
});

Creating Tasks with Dependencies

// Create a task that depends on other tasks
await mcp.callTool("create-task", {
  title: "Integration Testing",
  blocking_task_ids: ["feature-impl-uuid", "unit-tests-uuid"],
});

Dependency Filtering

// Get blocked tasks
await mcp.callTool("search-tasks", {
  blocked_only: true,
  limit: 10,
});

// Get tasks ready to start
await mcp.callTool("search-tasks", {
  can_be_started: true,
  limit: 10,
});

Dependency Resources

// Browse dependency data
await mcp.readResource("outcomeOS://task-dependencies");
await mcp.readResource("outcomeOS://tasks/blocked");
await mcp.readResource("outcomeOS://tasks/blocking");

Testing

# Basic protocol test
npx @outcomeos/mcp-server
# Should connect and show available tools

# Test with your API key
export OUTCOMEOS_API_KEY="ok_your_key"
npx @outcomeos/mcp-server
# Should connect to your OutcomeOS instance

# Custom base URL
export OUTCOMEOS_BASE_URL="https://app.outcomeos.io"
npx @outcomeos/mcp-server

Development

Local Development Setup

git clone https://github.com/outcomeos/outcomeOS.git
cd outcomeOS/mcp
npm install
npm run dev  # Starts with hot reload

Building

npm run build   # Compiles TypeScript
npm run start   # Runs compiled version

Testing Changes

npm run build && npx @outcomeos/mcp-server --version

Support & Community

• Documentation: OutcomeOS MCP Guide
• Issues: GitHub Issues
• Community: OutcomeOS Discussions

License

MIT License - see LICENSE file for details.

Ready to supercharge your productivity? Start with npx @outcomeos/mcp-server and connect your AI assistant to OutcomeOS! 🚀