beads/website/docs/integrations/mcp-server.md
Scott Nixon 18f47fe8b6
docs: add GitHub Copilot integration guide with cross-platform MCP paths (#1348)
* fix(export): populate export_hashes after successful export (GH#1278)

Child issues created with --parent were missing from export_hashes table,
which affects integrity tracking and future incremental export features.

This fix ensures SetExportHash() is called for all exported issues:
- Updated ExportResult to include IssueContentHashes map
- Updated finalizeExport() to call SetExportHash() for each exported issue
- Updated exportToJSONLDeferred() to collect content hashes during export
- Updated performIncrementalExport() to collect content hashes for dirty issues
- Updated exportToJSONLWithStore() to call SetExportHash() after export
- Updated daemon's handleExport() to call SetExportHash() after export

Added test TestExportPopulatesExportHashes to verify the fix works for
both regular and hierarchical (child) issue IDs.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: add GitHub Copilot integration guide

Add comprehensive documentation for using beads with GitHub Copilot in VS Code via the MCP server.

New files:
- docs/COPILOT_INTEGRATION.md - Complete setup guide with prerequisites, MCP tools reference, example workflows, troubleshooting, and FAQ
- website/docs/integrations/github-copilot.md - Shorter website version

Updated files:
- docs/INSTALLING.md - Added GitHub Copilot row to setup matrix and new "GitHub Copilot (VS Code)" section with quick setup steps
- website/docs/getting-started/ide-setup.md - Added GitHub Copilot section
- website/docs/integrations/mcp-server.md - Added VS Code / GitHub Copilot configuration examples for both .vscode/mcp.json and settings.json

Key clarifications:
- Beads is a system-wide CLI tool installed once, not cloned into projects
- The .beads/ directory only contains the issue database
- Added FAQ addressing "Do I need to clone beads?" explicitly

Fixes #148

* docs: add cross-platform paths for user-level VS Code MCP config

  Add Linux and Windows paths alongside macOS for the VS Code
  user-level MCP configuration. Users can now find the correct
  path for their platform in a simple table format.

  Paths by platform:
  - macOS: ~/Library/Application Support/Code/User/mcp.json
  - Linux: ~/.config/Code/User/mcp.json
  - Windows: %APPDATA%\Code\User\mcp.json

  Fixes #148

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-27 11:25:14 -08: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