beads-mcp

MCP server for beads issue tracker and agentic memory system. Enables AI agents to manage tasks using bd CLI through Model Context Protocol.

Note: 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. See the main README for CLI setup.

Use this MCP server for MCP-only environments like Claude Desktop where CLI access is unavailable.

Installing

Install from PyPI:

# Using uv (recommended)
uv tool install beads-mcp

# Or using pip
pip install beads-mcp

Add to your Claude Desktop config:

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

Development Installation

For development, clone the repository:

git clone https://github.com/gastownhall/beads
cd beads/integrations/beads-mcp
uv sync

Then use in Claude Desktop config:

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

Environment Variables (all optional):

BEADS_PATH - Path to bd executable (default: ~/.local/bin/bd)
BEADS_DB - Path to beads database file (default: auto-discover from cwd)
BEADS_WORKING_DIR - Working directory for bd commands (default: $PWD or current directory). Used for multi-repo setups - see below
BEADS_ACTOR - Actor name for audit trail (default: $USER)
BEADS_NO_AUTO_FLUSH - Disable automatic sync (default: false)
BEADS_NO_AUTO_IMPORT - Disable automatic import (default: false)

Multi-Repository Setup

Recommended: Use a single MCP server instance for all beads projects - it automatically routes to per-project Dolt servers.

Single MCP Server (Recommended)

Simple config - works for all projects:

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

How it works (LSP model):

MCP server detects the beads project in your current workspace
Routes requests to the per-project Dolt server based on working directory
Auto-starts the local Dolt server if not running
Each project gets its own isolated Dolt server serving only its database

Architecture:

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

Why per-project Dolt servers?

Complete database isolation between projects
No cross-project pollution or git worktree conflicts
Simpler mental model: one project = one database = one Dolt server
Follows LSP (Language Server Protocol) architecture
One MCP config works for unlimited projects

Alternative: Per-Project MCP Instances (Not Recommended)

Configure separate MCP servers for specific projects using BEADS_WORKING_DIR:

{
  "mcpServers": {
    "beads-webapp": {
      "command": "beads-mcp",
      "env": {
        "BEADS_WORKING_DIR": "/Users/yourname/projects/webapp"
      }
    },
    "beads-api": {
      "command": "beads-mcp",
      "env": {
        "BEADS_WORKING_DIR": "/Users/yourname/projects/api"
      }
    }
  }
}

⚠️ Problem: AI may select the wrong MCP server for your workspace, causing commands to operate on the wrong database. Use single MCP server instead.

Multi-Project Support

The MCP server supports managing multiple beads projects in a single session using per-request workspace routing.

Using `workspace_root` Parameter

Every tool accepts an optional workspace_root parameter for explicit project targeting:

# 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"
)

Architecture

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)

ContextVar Routing: Per-request workspace context is managed via Python's ContextVar:

Each tool call sets the workspace for its duration
Properly isolated for concurrent calls (no cross-contamination)
Falls back to BEADS_WORKING_DIR if workspace_root not provided

Path Canonicalization:

Symlinks are resolved to physical paths (prevents duplicate connections)
Git submodules with .beads directories use local context
Git toplevel is used for non-initialized directories
Results are cached for performance

Backward Compatibility

The set_context() tool still works and sets a default workspace:

# Old way (still supported)
await set_context(workspace_root="/Users/you/project-a")
await beads_ready_work()  # Uses project-a

# New way (more flexible)
await beads_ready_work(workspace_root="/Users/you/project-a")

Concurrency Gotchas

⚠️ IMPORTANT: Tool implementations must NOT spawn background tasks using asyncio.create_task().

Why? ContextVar doesn't propagate to spawned tasks, which can cause cross-project data leakage.

Solution: Keep all tool logic synchronous or use sequential await calls.

Troubleshooting

Symlink aliasing: Different paths to same project are deduplicated automatically via realpath.

Submodule handling: Submodules with their own .beads directory are treated as separate projects.

Stale connections: Currently no health checks. Phase 2 will add retry-on-failure if monitoring shows need.

Version mismatches: Dolt server version is auto-checked. Mismatched servers are automatically restarted.

Features

Resource:

beads://quickstart - Quickstart guide for using beads

Tools (all support workspace_root parameter):

init - Initialize bd in current directory
create - Create new issue (bug, feature, task, epic, chore, decision)
list - List issues with filters (status, priority, type, assignee)
ready - Find tasks with no blockers ready to work on
show - Show detailed issue info including dependencies
update - Update issue (status, priority, design, notes, etc). Note: status="closed" or status="open" automatically route to close or reopen tools to respect approval workflows
close - Close completed issue
dep - Add dependency (blocks, related, parent-child, discovered-from)
comment - Add a durable, timestamped comment to an issue (a record of work/decisions)
comments - List all comments on an issue (show reports comment_count but not the bodies)
note - Append a note to an issue's notes field
blocked - Get blocked issues
stats - Get project statistics
reopen - Reopen a closed issue with optional reason
set_context - Set default workspace for subsequent calls (backward compatibility)

Known Issues

MCP Tools Not Loading in Claude Code (Issue #346) - RESOLVED

Status: ✅ Fixed in v0.24.0+

This issue affected versions prior to v0.24.0. The problem was caused by self-referential Pydantic models (Issue with dependencies: list["Issue"]) generating invalid MCP schemas with $ref at root level.

Solution: The issue was fixed in commit f3a678f by refactoring the data models:

Created IssueBase with common fields
Created LinkedIssue(IssueBase) for dependency references
Changed Issue to use list[LinkedIssue] instead of list["Issue"]

This breaks the circular reference and ensures all tool outputSchemas have type: object at root level.

Upgrade: If you're running beads-mcp < 0.24.0:

pip install --upgrade beads-mcp

All MCP tools now load correctly in Claude Code with v0.24.0+.

Development

Baseline validation:

uv sync
uv run pytest
uv run python -m build

Integration tests require a current bd binary from this repository. In particular, bd init --help must include --non-interactive, --skip-agents, and --skip-hooks; older installed versions are skipped with a clear pytest message.

Run MCP inspector:

# inside beads-mcp dir
uv run fastmcp dev src/beads_mcp/server.py

Type checking (source maintenance, not part of baseline validation yet):

uv run mypy src/beads_mcp

Linting and formatting (source maintenance, not part of baseline validation yet):

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/

Test suite includes both mocked unit tests and integration tests with real bd CLI.

Multi-Repo Integration Test

Test Dolt server with multiple repositories:

# Start the Dolt server first
cd /path/to/beads
bd dolt start

# Run multi-repo test
cd integrations/beads-mcp
uv run python test_multi_repo.py

This test verifies that the Dolt server can handle operations across multiple repositories simultaneously using per-request context routing.

Metadata

Release files for beads-mcp 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for beads-mcp 1.3.0
File	Size	Uploaded
beads_mcp-1.3.0.tar.gz	233.0 kB	Sep 15, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for beads-mcp 1.3.0
File	Interpreter	ABI	Platform	Reset
beads_mcp-1.3.0-py3-none-any.whl 38.5 kB Sep 15, 2026	Python 3	none	any	Details

Total release size: 271.4 kB

Release files / beads_mcp-1.3.0.tar.gz

Download URL	beads_mcp-1.3.0.tar.gz
Size	233.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`72b5a10fef4096b6d111ab1e53fcbeda9e499b59658e421d50de5db52c8d97d6`
BLAKE2b-256 checksum How to use checksums	`4ce7222bf62be701a5284374a06cf458733f031887d1ce0540e81db6d903cbb7`
Upload date	Sep 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`

Release files / beads_mcp-1.3.0-py3-none-any.whl

Download URL	beads_mcp-1.3.0-py3-none-any.whl
Size	38.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`e8753c89954650025cd31c572d2d3c8f555181ffa37007e114b6c51bd00063a1`
BLAKE2b-256 checksum How to use checksums	`15af000548c428701733891f2a135a1a2e92303e73971490890461091ff87499`
Upload date	Sep 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`