npm package: @outcomeos/mcp-server
Description: OutcomeOS MCP (Model Context Protocol) Server - Connect AI assistants to OutcomeOS for task management, analytics, and workflow automation
Author: OutcomeOS
Latest version: 2.3.6

# OutcomeOS MCP Server

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

[![npm version](https://badge.fury.io/js/@outcomeos%2Fmcp-server.svg)](https://badge.fury.io/js/@outcomeos%2Fmcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Quick Start

Get started in 30 seconds:

```bash
npx @outcomeos/mcp-server --help
```

## What is This?

The **OutcomeOS MCP Server** is a [Model Context Protocol](https://modelcontextprotocol.io/) 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! 🚀

```json
{
  "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:

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

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

### Option 2: Global Install

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

### Option 3: Local Development

```bash
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

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

### With Team Context

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

### Custom Instance

```bash
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`):

```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:

```json
{
  "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

```typescript
// 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

```typescript
// 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

```typescript
// 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

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

## Testing

```bash
# 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

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

### Building

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

### Testing Changes

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

## Support & Community

- **Documentation**: [OutcomeOS MCP Guide](https://github.com/outcomeos/outcomeOS/tree/main/mcp)
- **Issues**: [GitHub Issues](https://github.com/outcomeos/outcomeOS/issues)
- **Community**: [OutcomeOS Discussions](https://github.com/outcomeos/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! 🚀