MCP Server

The Beads MCP (Model Context Protocol) server enables AI agents to manage issues through native tool calls. This is ideal for MCP-only environments like Claude Desktop.

For environments with shell access (Claude Code, Cursor, Windsurf), the CLI + hooks approach is recommended over MCP. It uses ~1-2k tokens vs 10-50k for MCP schemas, resulting in lower compute cost and latency.

When to Use MCP

Use MCP

Claude Desktop (no shell access)
VS Code with GitHub Copilot
MCP-only environments
Natural language interfaces

Use CLI + Hooks

Claude Code
Cursor
Windsurf
Any environment with shell access

Installation

Install beads-mcp

Install from PyPI using uv (recommended):

uv tool install beads-mcp

Alternative installation methods:

# Using pip
pip install beads-mcp

# Using pipx
pipx install beads-mcp

Configure your AI client

Claude Desktop
VS Code (Copilot)
Development

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}

Create or edit .vscode/mcp.json in your project:

{
  "servers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}

Or configure globally at:

macOS: ~/Library/Application Support/Code/User/mcp.json
Linux: ~/.config/Code/User/mcp.json
Windows: %APPDATA%\Code\User\mcp.json

For development with local clone:

{
  "mcpServers": {
    "beads": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/beads-mcp",
        "run",
        "beads-mcp"
      ]
    }
  }
}

Initialize Beads in your project

cd your-project
bd init --quiet

Restart your AI client

Restart Claude Desktop or reload VS Code window for configuration to take effect.

Available Tools

All tools support an optional workspace_root parameter for multi-project setups.

Tool	Description	Example
`beads_init`	Initialize bd in directory	”Initialize beads here”
`beads_create`	Create new issue	”Create a bug for login timeout”
`beads_list`	List issues with filters	”Show all P1 bugs”
`beads_ready`	Find unblocked work	”What can I work on?”
`beads_show`	Show issue details	”Show bd-42”
`beads_update`	Update issue fields	”Set bd-42 to in-progress”
`beads_close`	Close completed issue	”Close bd-42 as done”
`beads_reopen`	Reopen closed issue	”Reopen bd-42”
`beads_dep`	Add dependency	”bd-99 blocks bd-42”
`beads_dep_tree`	Show dependency tree	”What blocks bd-42?”
`beads_blocked`	Get blocked issues	”Show blocked issues”
`beads_stats`	Get project statistics	”Show project stats”
`beads_sync`	Sync to git	”Sync beads to git”
`set_context`	Set default workspace	”Use /path/to/project”

Resources

Resource	Description
`beads://quickstart`	Quickstart guide for using beads

Multi-Repository Setup

Single MCP Server (Recommended)

Use one MCP server instance for all projects:

{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}

How it works:

MCP server detects the beads project in your current workspace
Routes requests to the per-project Dolt server
Auto-starts local Dolt server if not running
Each project gets isolated database access

Architecture:

MCP Server (one instance)
    ↓
Per-Project Dolt Servers (one per workspace)
    ↓
Dolt Databases (complete isolation)

Multi-Project Support

Every tool accepts an optional workspace_root parameter:

# Query issues from different projects concurrently
results = await asyncio.gather(
    beads_ready_work(workspace_root="/Users/you/project-a"),
    beads_ready_work(workspace_root="/Users/you/project-b"),
)

# Create issue in specific project
await beads_create_issue(
    title="Fix auth bug",
    priority=1,
    workspace_root="/Users/you/project-a"
)

Connection Pool

The MCP server maintains a connection pool keyed by canonical workspace path:

Each workspace gets its own Dolt server connection
Paths are canonicalized (symlinks resolved, git toplevel detected)
Concurrent requests use asyncio.Lock to prevent race conditions
No LRU eviction (keeps all connections open for session)

Environment Variables

All optional:

Variable	Description	Default
`BEADS_PATH`	Path to bd executable	`~/.local/bin/bd`
`BEADS_DB`	Path to beads database	Auto-discover from cwd
`BEADS_WORKING_DIR`	Working directory	`$PWD` or current directory
`BEADS_ACTOR`	Actor name for audit	`$USER`
`BEADS_NO_AUTO_FLUSH`	Disable auto sync	`false`
`BEADS_NO_AUTO_IMPORT`	Disable auto import	`false`

Usage Examples

Natural Language Queries

You: What issues are ready to work on?
Claude: [Calls beads_ready]
There are 3 issues ready:
1. [P1] bd-42: Fix authentication timeout
2. [P2] bd-99: Add password reset flow
3. [P3] bd-17: Update API documentation

Creating Issues

You: Create a bug for the login timeout
Claude: [Calls beads_create]
Created bd-123: Fix login timeout [P1, bug]

Updating Issues

You: Set bd-42 to in-progress and claim it
Claude: [Calls beads_update]
Updated bd-42: status=in-progress, claimed by you

Tracking Dependencies

You: bd-99 blocks bd-42
Claude: [Calls beads_dep]
Added dependency: bd-99 blocks bd-42

Completing Work

You: Close bd-42 as done
Claude: [Calls beads_close]
Closed bd-42: Fix authentication timeout

You: Sync to git
Claude: [Calls beads_sync]
Synced 1 issue to git

Troubleshooting

MCP tools not loading

Check installation:

which beads-mcp
beads-mcp --version

Verify PATH:

# If installed with uv
export PATH="$HOME/.local/bin:$PATH"

# Reinstall if needed
uv tool install beads-mcp --force

Restart client:

Claude Desktop: Quit and relaunch
VS Code: Reload window (Cmd/Ctrl + Shift + P → “Reload Window”)

No beads database found

Initialize beads in your project:

cd your-project
bd init --quiet

Wrong database detected

Check current context:

You: Where am I?
Claude: [Calls where_am_i]
Workspace: /path/to/project
Database: /path/to/project/.beads/prefix.db

Set explicit context:

You: Use /path/to/correct/project
Claude: [Calls set_context]
Context set to /path/to/correct/project

Stale connections

If you see connection issues, restart the Dolt server:

bd dolt stop
bd dolt start

The MCP server will automatically reconnect.

Version mismatches

Ensure bd and beads-mcp are up to date:

# Update bd
brew upgrade beads
# or
go install github.com/steveyegge/beads/cmd/bd@latest

# Update beads-mcp
uv tool install beads-mcp --upgrade

Token Overhead Comparison

MCP adds significant token overhead compared to CLI + hooks.

Approach	Token Overhead	Compute Cost	Latency
CLI + Hooks	~1-2k tokens	Low	Fast
MCP Server	~10-50k tokens	High (10-50x)	Slower

Why the difference?

MCP requires full tool schemas in context
Each tool adds 1-5k tokens for schema definition
CLI just injects workflow instructions (~1-2k total)

When context doesn’t matter:

Very short conversations
MCP-only environments (no alternative)

When to prefer CLI:

Long conversations or coding sessions
Any environment with shell access
Multi-editor workflows

Development

Run MCP Inspector

cd beads/integrations/beads-mcp
uv run fastmcp dev src/beads_mcp/server.py

Type Checking

uv run mypy src/beads_mcp

Linting and Formatting

uv run ruff check src/beads_mcp
uv run ruff format src/beads_mcp

Testing

# Run all tests
uv run pytest

# With coverage
uv run pytest --cov=beads_mcp tests/

# Multi-repo integration test
bd dolt start
uv run python test_multi_repo.py

Claude Code

Recommended CLI + hooks integration

GitHub Copilot

Use MCP with VS Code Copilot

Aider Integration

Human-in-the-loop AI pair programming

Quick Start

Learn Beads basics

Get Started

Core Concepts

Guides

Integrations

When to Use MCP

Use MCP

Use CLI + Hooks

Installation

Available Tools

Resources

Multi-Repository Setup

Single MCP Server (Recommended)

Multi-Project Support

Connection Pool

Environment Variables

Usage Examples

Natural Language Queries

Creating Issues

Updating Issues

Tracking Dependencies

Completing Work

Troubleshooting

Token Overhead Comparison

Development

Run MCP Inspector

Type Checking

Linting and Formatting

Testing

See Also

Claude Code

GitHub Copilot

Aider Integration

Quick Start

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Integrations

Documentation Index

​When to Use MCP

Use MCP

Use CLI + Hooks

​Installation

​Available Tools

​Resources

​Multi-Repository Setup

​Single MCP Server (Recommended)

​Multi-Project Support

​Connection Pool

​Environment Variables

​Usage Examples

​Natural Language Queries

​Creating Issues

​Updating Issues

​Tracking Dependencies

​Completing Work

​Troubleshooting

​Token Overhead Comparison

​Development

​Run MCP Inspector

​Type Checking

​Linting and Formatting

​Testing

​See Also

Claude Code

GitHub Copilot

Aider Integration

Quick Start

Build docs developers (and LLMs) love

When to Use MCP

Installation

Available Tools

Resources

Multi-Repository Setup

Single MCP Server (Recommended)

Multi-Project Support

Connection Pool

Environment Variables

Usage Examples

Natural Language Queries

Creating Issues

Updating Issues

Tracking Dependencies

Completing Work

Troubleshooting

Token Overhead Comparison

Development

Run MCP Inspector

Type Checking

Linting and Formatting

Testing

See Also