Beads MCP server for AI agents

The beads-mcp server allows AI agents to manage tasks through the Model Context Protocol, providing a bridge to the beads issue tracking system. This solution is particularly useful for environments like Claude Desktop where direct CLI access is unavailable.

Installation

Standard Installation

Install the beads-mcp server from PyPI:

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

# Or using pip
pip install beads-mcp

Add the server to your Claude Desktop configuration:

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

Environment Variables

All environment variables are optional:

BEADS_USE_DAEMON - Use daemon RPC instead of CLI (default: 1, set to 0 to disable)
BEADS_PATH - Path to bd executable (default: ~/.local/bin/bd)
BEADS_DB - Path to beads database file (default: auto-discover from current directory)
BEADS_WORKING_DIR - Working directory for bd commands (default: current directory)
BEADS_ACTOR - Actor name for audit trail (default: $USER)
BEADS_NO_AUTO_FLUSH - Disable automatic JSONL sync (default: false)
BEADS_NO_AUTO_IMPORT - Disable automatic JSONL import (default: false)

Multi-Repository Setup

Single MCP Server (Recommended)

The recommended approach is to use a single MCP server instance for all beads projects:

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

How it works:

The MCP server checks for a local daemon socket (.beads/bd.sock) in your current workspace
It routes requests to the per-project daemon based on working directory
It automatically starts the local daemon if not running
Each project gets its own isolated daemon serving only its database

Alternative: Per-Project MCP Instances (Not Recommended)

You can configure separate MCP servers for specific projects using environment variables:

{
  "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"
      }
    }
  }
}

⚠️ Warning: This approach may lead to the AI selecting the wrong MCP server for your workspace, causing commands to operate on the wrong database.

Multi-Project Support

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

Backward Compatibility

The set_context() tool is still supported for setting 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")

Available Tools

All of these tools support the workspace_root parameter:

init - Initialize bd in current directory
create - Create new issue (bug, feature, task, epic, chore)
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)
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

Resources

The MCP server provides the following resource:

beads://quickstart - Quickstart guide for using beads

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "beads" '{"command":"beads-mcp"}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect

Beads MCP server