> ## Documentation Index
> Fetch the complete documentation index at: https://beads.gascity.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
uv tool install beads-mcp
```

### Using pip

```bash theme={null}
pip install beads-mcp
```

## Configuration

### Claude Desktop (macOS)

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}
```

### Claude Desktop (Windows)

Add to `%APPDATA%\Claude\claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}
```

### Sourcegraph Amp

Add to MCP settings:

```json theme={null}
{
  "beads": {
    "command": "beads-mcp",
    "args": []
  }
}
```

### VS Code / GitHub Copilot

Create `.vscode/mcp.json` in your project:

```json theme={null}
{
  "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` |

```json theme={null}
{
  "servers": {
    "beads": {
      "command": "beads-mcp",
      "args": []
    }
  }
}
```

**Note:** Requires VS Code 1.96+ with MCP support enabled.

See [GitHub Copilot Integration](/integrations/github-copilot) 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:

```bash theme={null}
which beads-mcp
```

If not found:

```bash theme={null}
# 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

```bash theme={null}
# Check directory permissions
ls -la .beads/

# Initialize if needed
bd init --quiet
```

## See Also

* [Claude Code](/integrations/claude-code) - CLI integration
* [Installation](/getting-started/installation) - Full install guide


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.