Skip to main content
Use beads in MCP-only environments.

​
When to Use MCP

Use MCP server when CLI is unavailable:
  • Claude Desktop (no shell access)
  • Sourcegraph Amp without shell
  • Other MCP-only environments
Prefer CLI + hooks when shell is available - it’s more context efficient.

​
Installation

uv tool install beads-mcp

​
Using pip

pip install beads-mcp

​
Configuration

​
Claude Desktop (macOS)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json: 
{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}

​
Claude Desktop (Windows)

Add to %APPDATA%\Claude\claude_desktop_config.json: 
{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}

​
Sourcegraph Amp

Add to MCP settings: 
{
  "beads": {
    "command": "beads-mcp",
    "args": []
  }
}

​
VS Code / GitHub Copilot

Create .vscode/mcp.json in your project: 
{
  "servers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}
For all projects: Add to VS Code user-level MCP config:
PlatformPath
macOS~/Library/Application Support/Code/User/mcp.json
Linux~/.config/Code/User/mcp.json
Windows%APPDATA%\Code\User\mcp.json
{
  "servers": {
    "beads": {
      "command": "beads-mcp",
      "args": []
    }
  }
}
Note: Requires VS Code 1.96+ with MCP support enabled. See GitHub Copilot Integration for complete setup guide.

​
Available Tools

The MCP server exposes these tools:
ToolDescription
readyShow ready work (no open blockers)
listList issues with filters
showShow issue details, dependencies, and dependents
createCreate a new issue
claimAtomically claim an issue
updateUpdate an issue
close / reopenClose or reopen an issue
depManage dependencies
comment / commentsAdd or list comments
noteAppend to an issue’s notes
blockedShow blocked issues and their blockers
stats / contextDatabase stats and workspace context
adminAdministrative operations
discover_tools / get_tool_infoTool discovery and schemas
There is no MCP sync tool — syncing stays on the CLI (bd dolt push / bd dolt pull).

​
Usage

Once configured, use naturally: 
Create an issue for fixing the login bug with priority 1
The MCP server translates to appropriate bd commands.

​
Trade-offs

AspectCLI + HooksMCP Server
Context overhead~1-2k tokens10-50k tokens
LatencyDirect callsMCP protocol
SetupHooks configMCP config
AvailabilityShell requiredMCP environments

​
Troubleshooting

​
Server won’t start

Check if beads-mcp is in PATH: 
which beads-mcp
If not found: 
# Reinstall
pip uninstall beads-mcp
pip install beads-mcp

​
Tools not appearing

  1. Restart Claude Desktop
  2. Check MCP config JSON syntax
  3. Verify server path

​
Permission errors

# Check directory permissions
ls -la .beads/

# Initialize if needed
bd init --quiet

​
See Also