MCP Server

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

Using uv (Recommended)

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:

Platform	Path
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:

Tool	Description
`ready`	Show ready work (no open blockers)
`list`	List issues with filters
`show`	Show issue details, dependencies, and dependents
`create`	Create a new issue
`claim`	Atomically claim an issue
`update`	Update an issue
`close` / `reopen`	Close or reopen an issue
`dep`	Manage dependencies
`comment` / `comments`	Add or list comments
`note`	Append to an issue’s notes
`blocked`	Show blocked issues and their blockers
`stats` / `context`	Database stats and workspace context
`admin`	Administrative operations
`discover_tools` / `get_tool_info`	Tool 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

Aspect	CLI + Hooks	MCP Server
Context overhead	~1-2k tokens	10-50k tokens
Latency	Direct calls	MCP protocol
Setup	Hooks config	MCP config
Availability	Shell required	MCP 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

Restart Claude Desktop
Check MCP config JSON syntax
Verify server path

Permission errors

# Check directory permissions
ls -la .beads/

# Initialize if needed
bd init --quiet

Getting Started

Core Concepts

Architecture

Workflows

Recovery

Multi-Agent

Integrations

Community

Reference

When to Use MCP

Installation

Using uv (Recommended)

Using pip

Configuration

Claude Desktop (macOS)

Claude Desktop (Windows)

Sourcegraph Amp

VS Code / GitHub Copilot

Available Tools

Usage

Trade-offs

Troubleshooting

Server won’t start

Tools not appearing

Permission errors

See Also

​When to Use MCP

​Installation

​Using uv (Recommended)

​Using pip

​Configuration

​Claude Desktop (macOS)

​Claude Desktop (Windows)

​Sourcegraph Amp

​VS Code / GitHub Copilot

​Available Tools

​Usage

​Trade-offs

​Troubleshooting

​Server won’t start

​Tools not appearing

​Permission errors

​See Also

When to Use MCP

Installation

Using uv (Recommended)

Using pip

Configuration

Claude Desktop (macOS)

Claude Desktop (Windows)

Sourcegraph Amp

VS Code / GitHub Copilot

Available Tools

Usage

Trade-offs

Troubleshooting

Server won’t start

Tools not appearing

Permission errors

See Also