- FAQ: fix bulk migration/export commands (tracker pull/push need explicit IDs; bulk lives on sync --pull-only / --pull / --push-only / --push) and correct the cross-project isolation claim (hydration + external targets) - quickstart: replace the broken DOLT.md blob URL with site links - installation: Quick Install Script heading matches its macOS/Linux/FreeBSD body - rewrite 33 stale SCREAMING_CASE link labels to the target pages' titles - add description frontmatter to the 55 authored pages missing it - docs.json: wildcard redirects for the old /next/ and version-prefixed route spaces (1.0.0, 1.0.4, 1.0.5)
3.5 KiB
3.5 KiB
| title | description |
|---|---|
| MCP Server | Run the beads-mcp server for MCP-only environments like Claude Desktop where the bd CLI is unavailable |
Use beads in MCP-only environments.
When to Use MCP
Use MCP server when CLI is unavailable:
- Claude Desktop (no shell access)
- Sourcegraph Amp without shell
- Other MCP-only environments
Prefer CLI + hooks when shell is available - it's more context efficient.
Installation
Using uv (Recommended)
uv tool install beads-mcp
Using pip
pip install beads-mcp
Configuration
Claude Desktop (macOS)
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"beads": {
"command": "beads-mcp"
}
}
}
Claude Desktop (Windows)
Add to %APPDATA%\Claude\claude_desktop_config.json:
{
"mcpServers": {
"beads": {
"command": "beads-mcp"
}
}
}
Sourcegraph Amp
Add to MCP settings:
{
"beads": {
"command": "beads-mcp",
"args": []
}
}
VS Code / GitHub Copilot
Create .vscode/mcp.json in your project:
{
"servers": {
"beads": {
"command": "beads-mcp"
}
}
}
For all projects: Add to VS Code user-level MCP config:
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/Code/User/mcp.json |
| Linux | ~/.config/Code/User/mcp.json |
| Windows | %APPDATA%\Code\User\mcp.json |
{
"servers": {
"beads": {
"command": "beads-mcp",
"args": []
}
}
}
Note: Requires VS Code 1.96+ with MCP support enabled.
See GitHub Copilot Integration for complete setup guide.
Available Tools
The MCP server exposes these tools:
| Tool | Description |
|---|---|
ready |
Show ready work (no open blockers) |
list |
List issues with filters |
show |
Show issue details, dependencies, and dependents |
create |
Create a new issue |
claim |
Atomically claim an issue |
update |
Update an issue |
close / reopen |
Close or reopen an issue |
dep |
Manage dependencies |
comment / comments |
Add or list comments |
note |
Append to an issue's notes |
blocked |
Show blocked issues and their blockers |
stats / context |
Database stats and workspace context |
admin |
Administrative operations |
discover_tools / get_tool_info |
Tool discovery and schemas |
There is no MCP sync tool — syncing stays on the CLI (bd dolt push /
bd dolt pull).
Usage
Once configured, use naturally:
Create an issue for fixing the login bug with priority 1
The MCP server translates to appropriate bd commands.
Trade-offs
| Aspect | CLI + Hooks | MCP Server |
|---|---|---|
| Context overhead | ~1-2k tokens | 10-50k tokens |
| Latency | Direct calls | MCP protocol |
| Setup | Hooks config | MCP config |
| Availability | Shell required | MCP environments |
Troubleshooting
Server won't start
Check if beads-mcp is in PATH:
which beads-mcp
If not found:
# Reinstall
pip uninstall beads-mcp
pip install beads-mcp
Tools not appearing
- Restart Claude Desktop
- Check MCP config JSON syntax
- Verify server path
Permission errors
# Check directory permissions
ls -la .beads/
# Initialize if needed
bd init --quiet
See Also
- Claude Code - CLI integration
- Installation - Full install guide