beads-mcp

# beads-mcp MCP server for [beads](https://github.com/gastownhall/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](../../README.md) for CLI setup. > > **Use this MCP server** for MCP-only environments like Claude Desktop where CLI access is unavailable. ## Installing Install from PyPI: ```bash # Using uv (recommended) uv tool install beads-mcp # Or using pip pip install beads-mcp ``` Add to your Claude Desktop config: ```json { "mcpServers": { "beads": { "command": "beads-mcp" } } } ``` ### Development Installation For development, clone the repository: ```bash git clone https://github.com/gastownhall/beads cd beads/integrations/beads-mcp uv sync ``` Then use in Claude Desktop config: ```json { "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…