Beads MCP Server¶

This MCP (Model Context Protocol) server exposes bd (beads) issue tracker commands as tools in Cursor IDE and Claude Code, enabling AI-powered issue management with automatic ClickUp synchronization.

Features¶

The MCP server provides these tools in Cursor:

bd_create - Create new issues with automatic ClickUp sync
bd_list - List and filter issues
bd_show - Show detailed issue information
bd_update - Update issues (auto-syncs to ClickUp)
bd_close - Close issues (auto-sets end date, adds commit/PR links)
bd_search - Search issues by keyword

All commands automatically sync to ClickUp with: - Status tracking with comments - Start date (when moved to in_progress) - End date (when closed) - Close reason tracking - Automatic commit/PR link detection

Installation¶

Recommended: Use the Setup Script¶

The fastest way to configure the MCP server is to run scripts/setup.sh — it sets up both Cursor and Claude Code automatically:

~/projects/bd-clickup-integration/scripts/setup.sh

Select "Setup Cursor MCP" and/or "Copy beads skills to .cursor/skills/" when prompted. The script writes ~/.cursor/mcp.json and the Claude Code plugin settings for you.

Manual: Cursor IDE¶

Step 1: Install the package

uv tool install git+https://github.com/latentsp/bd-clickup-integration.git

This installs the beads-mcp-server binary.

Step 2: Configure Cursor

Create or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp-server",
      "env": {
        "BEADS_PROJECT_DIR": "/path/to/your/beads/project",
        "CLICKUP_API_TOKEN": "pk_..."
      }
    }
  }
}

Required: Set BEADS_PROJECT_DIR to the directory containing .beads.

Step 3: Restart Cursor

Restart Cursor IDE to load the MCP server.

Manual: Claude Code¶

Claude Code loads the MCP server via the beads-clickup plugin. The setup script configures this automatically, but you can also do it manually:

Add to .claude/settings.json in your project:

{
  "extraKnownMarketplaces": {
    "beads-clickup": {
      "source": { "source": "github", "repo": "latentsp/bd-clickup-integration" }
    }
  },
  "enabledPlugins": { "beads-clickup@beads-clickup": true }
}

Claude Code will prompt to install the plugin on next launch.

Usage in Cursor¶

Once configured, you can use natural language to interact with beads through Cursor's AI:

Examples¶

Create an issue:

Create a new beads issue titled "Fix login bug" with priority p1 and type bug

List issues:

Show me all open beads issues

Update an issue:

Move issue vectordb-99w to in_progress status

Close an issue:

Close issue vectordb-99w with reason "Fixed in PR #123"

Search issues:

Search beads issues for "database"

The AI will automatically: - Use the appropriate MCP tool - Provide the correct parameters - Show you the results - Sync changes to ClickUp in the background

Advanced Configuration¶

Environment Variables¶

Variable	Required	Description
`BEADS_PROJECT_DIR`	Yes	Path to your project directory (the one containing `.beads`)
`CLICKUP_API_TOKEN`	No	ClickUp API token (can also be set in project `.env`)
`BEADS_DB`	No	Path to custom beads database

Example: If your project is at /home/username/projects/myproject and it has a .beads directory, set:

"BEADS_PROJECT_DIR": "/home/username/projects/myproject"

The MCP server uses this directory for all bd commands, ensuring they run in the correct project context.

Testing the MCP Server¶

Test the server manually:

# Start the server
beads-mcp-server

# Send a test request (in another terminal)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | beads-mcp-server

Available Tools¶

bd_create¶

Create a new beads issue with automatic ClickUp sync.

Parameters: - title (required): Issue title - priority (optional): p0, p1, p2, p3, or p4 - type (optional): bug, feature, task, etc. - description (optional): Issue description

bd_list¶

List all beads issues.

Parameters: - status (optional): Filter by status (open, in_progress, completed, closed) - priority (optional): Filter by priority (p0-p4)

bd_show¶

Show details of a specific beads issue.

Parameters: - issue_id (required): Issue ID (e.g., project-abc)

bd_update¶

Update a beads issue with automatic ClickUp sync.

Parameters: - issue_id (required): Issue ID - status (optional): New status - priority (optional): New priority - title (optional): New title - description (optional): New description

bd_close¶

Close a beads issue with automatic ClickUp sync.

Parameters: - issue_id (required): Issue ID - reason (optional): Close reason

bd_search¶

Search beads issues by keyword.

Parameters: - query (required): Search query

Troubleshooting¶

MCP Server Not Showing Up¶

Check Cursor's MCP logs:
Open Cursor Developer Tools (Help -> Toggle Developer Tools)
Look for MCP-related errors in the Console
Verify the server works standalone:
```
beads-mcp-server
```
Check the binary is installed:
```
which beads-mcp-server
```

Commands Not Working¶

Ensure you're in a beads project:
```
bd list  # Should work in terminal
```

Check ClickUp integration:

# Verify config exists
cat .beads/integrations/clickup/config.yaml

Check environment variables:
```
echo $CLICKUP_API_TOKEN
```

MCP Server Can't Find Project Directory¶

If you get errors about BEADS_PROJECT_DIR not being set:

Set BEADS_PROJECT_DIR in your MCP config - this is required:

{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp-server",
      "env": {
        "BEADS_PROJECT_DIR": "/path/to/your/beads/project"
      }
    }
  }
}

Verify the project directory contains a .beads directory:
```
ls -la /path/to/your/beads/project/.beads
```

Test manually from that directory:

cd /path/to/your/beads/project
bd-clickup list

beads-mcp-server Not Found¶

If you get command not found: beads-mcp-server:

# Install via uv tool
uv tool install git+https://github.com/latentsp/bd-clickup-integration.git

# Or install in editable mode
uv add --editable ~/projects/bd-clickup-integration

Permission Issues¶

If you get permission errors:

chmod +x ~/projects/bd-clickup-integration/bd

More Information¶

Main README - Overall project documentation
Setup Guide - Detailed setup instructions
Quick Start - Get started quickly

Benefits¶

Using the MCP server in Cursor gives you:

Natural Language Interface - Just describe what you want
Automatic Sync - All changes sync to ClickUp automatically
Rich Tracking - Start/end dates, commit links, status comments
Context Aware - AI understands your project context
Faster Workflow - No need to switch between terminal and IDE

Questions? Open an issue or check the main documentation!