@works-cli/mcp-server

Native MCP (Model Context Protocol) server for Works integration with AI coding agents.

Supported Clients

• Claude Desktop - Native MCP support
• Cursor - Via MCP integration
• Windsurf - Via MCP integration
• Cline - Via MCP integration
• Any MCP-compatible client

Quick Start

1. Sign in once (credentials are stored locally):

npx @works-cli/cli login

2. Add to your IDE's MCP config:

{
  "mcpServers": {
    "works": {
      "command": "npx",
      "args": ["-y", "@works-cli/mcp-server"]
    }
  }
}

That's it! The MCP server will use your stored credentials automatically.

Installation (Optional)

Install globally if you prefer:

npm install -g @works-cli/mcp-server

Or run directly with npx (recommended):

npx @works-cli/mcp-server

IDE Configuration

Cursor

Add to Cursor Settings → Features → MCP:

{
  "mcpServers": {
    "works": {
      "command": "npx",
      "args": ["-y", "@works-cli/mcp-server"]
    }
  }
}

Windsurf

Add to Windsurf Settings → MCP Servers:

{
  "mcpServers": {
    "works": {
      "command": "npx",
      "args": ["-y", "@works-cli/mcp-server"]
    }
  }
}

Claude Desktop

Add to ~/.config/claude/config.json (Linux/Mac) or %APPDATA%\Claude\config.json (Windows):

{
  "mcpServers": {
    "works": {
      "command": "npx",
      "args": ["-y", "@works-cli/mcp-server"]
    }
  }
}

Cline

Configure in Cline's MCP settings panel:

• Command: npx
• Args: ["-y", "@works-cli/mcp-server"]

Authentication

The MCP server looks for credentials in this order:

1. Stored credentials from works login (recommended)
2. WORKS_API_KEY environment variable
3. --api-key command line argument

Using stored credentials (recommended)

npx @works-cli/cli login   # Sign in once
npx @works-cli/cli whoami  # Verify you're signed in

Using API key (alternative)

{
  "mcpServers": {
    "works": {
      "command": "npx",
      "args": ["-y", "@works-cli/mcp-server"],
      "env": {
        "WORKS_API_KEY": "your-api-key"
      }
    }
  }
}

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | WORKS_SERVER_URL | Backend server URL | https://api.works.select | | WORKS_API_KEY | API key for authentication | (none) |

Available Tools

All Works MCP tools are available:

• get_work_context - Get AGENTS.md specification for a work item
• search_work - Search for work items
• list_assigned_work - List work assigned to agents
• mark_complete - Mark work as completed
• report_progress - Report progress on work
• escalate_issue - Escalate blockers

How It Works

This MCP server acts as a proxy between MCP clients (Claude Desktop, Cursor, Cline) and the Works backend. It:

1. Receives MCP requests via stdio
2. Forwards them to the Works backend HTTP endpoint
3. Returns responses in MCP format

This allows native integration without requiring HTTP client setup in each AI tool.

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start