beads/website/versioned_docs/version-1.0.0/integrations/mcp-server.md
Isaac Karrer 7f0a165f4e
feat(docs): version Docusaurus site and align llms-full with snapshots (#3033)
* feat(docs): version Docusaurus site and align llms-full with snapshots

Add docs version 1.0.0, version dropdown, lastVersion defaulting to stable,
merged markdown config, and RELEASING steps for future doc snapshots.
generate-llms-full.sh reads the latest entry in versions.json.

README links the published documentation site.

Closes #2644

Made-with: Cursor

* fix(docs): update org URLs to gastownhall and refresh 1.0.0 snapshot

- Update default orgName in docusaurus.config.ts from steveyegge to
  gastownhall to match the repo's new home
- Update hardcoded steveyegge URLs in generate-llms-full.sh
- Refresh versioned_docs 1.0.0 snapshot to include quickstart changes
  from #3032 which merged after the original snapshot was taken
- Regenerate llms-full.txt with corrected URLs and updated content

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: matt wilkie <maphew@gmail.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-06 21:12:54 -07:00

3 KiB

id title sidebar_position
mcp-server MCP Server 2

MCP Server

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

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
beads_create Create new issue
beads_list List issues
beads_show Show issue details
beads_update Update issue
beads_close Close issue
beads_ready Show ready work
beads_sync Sync to git
beads_dep_add Add dependency
beads_dep_tree Show dependency tree

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

  1. Restart Claude Desktop
  2. Check MCP config JSON syntax
  3. Verify server path

Permission errors

# Check directory permissions
ls -la .beads/

# Initialize if needed
bd init --quiet

See Also