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