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)
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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

beads_mcp-1.2.2.tar.gz (176.0 kB view details)

Uploaded Aug 15, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

beads_mcp-1.2.2-py3-none-any.whl (36.7 kB view details)

Uploaded Aug 15, 2026 Python 3

File details

Details for the file beads_mcp-1.2.2.tar.gz.

File metadata

Download URL: beads_mcp-1.2.2.tar.gz
Upload date: Aug 15, 2026
Size: 176.0 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.14.7

File hashes

Hashes for beads_mcp-1.2.2.tar.gz
Algorithm	Hash digest
SHA256	`e37eb0bb832590c946be4fe697e023e85f5c3741eadc23d3d1d6ccc9eebaa514`
MD5	`6cb4204a39ab755f327594d3f783ec70`
BLAKE2b-256	`d8df9b7451f380ea2d8d78117b7a337256587b73d92df30c9532eae9c6ebe9fd`

See more details on using hashes here.

File details

Details for the file beads_mcp-1.2.2-py3-none-any.whl.

File metadata

Download URL: beads_mcp-1.2.2-py3-none-any.whl
Upload date: Aug 15, 2026
Size: 36.7 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.14.7

File hashes

Hashes for beads_mcp-1.2.2-py3-none-any.whl
Algorithm	Hash digest
SHA256	`312256f08e30e81f9935cb1b7a3e726f6e664e72adaa5ceb3f5273977efacd90`
MD5	`5acc6fb573426843d07bb8bdd8511646`
BLAKE2b-256	`5028a0c2be2a80aa17287ff9289e6979747bf969f6950ec5756623a0fd20e333`