584608a14e
Cherry-picked website/, scripts/generate-llms-full.sh, and deploy-docs.yml from joyshmitz's PR. Fixed workflow to trigger on main branch instead of docs/docusaurus-site. Features: - Docusaurus documentation site with llms.txt support - Environment-variable driven config (defaults to steveyegge org) - Automated llms-full.txt generation from docs - GitHub Pages deployment workflow Co-authored-by: joyshmitz <joyshmitz@users.noreply.github.com> 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Executed-By: beads/crew/dave Rig: beads Role: crew
150 lines
2.4 KiB
Markdown
150 lines
2.4 KiB
Markdown
---
|
|
id: mcp-server
|
|
title: MCP Server
|
|
sidebar_position: 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
|
|
|
|
### Using uv (Recommended)
|
|
|
|
```bash
|
|
uv tool install beads-mcp
|
|
```
|
|
|
|
### Using pip
|
|
|
|
```bash
|
|
pip install beads-mcp
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Claude Desktop (macOS)
|
|
|
|
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"beads": {
|
|
"command": "beads-mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Claude Desktop (Windows)
|
|
|
|
Add to `%APPDATA%\Claude\claude_desktop_config.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"beads": {
|
|
"command": "beads-mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Sourcegraph Amp
|
|
|
|
Add to MCP settings:
|
|
|
|
```json
|
|
{
|
|
"beads": {
|
|
"command": "beads-mcp",
|
|
"args": []
|
|
}
|
|
}
|
|
```
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
which beads-mcp
|
|
```
|
|
|
|
If not found:
|
|
|
|
```bash
|
|
# 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
|
|
# 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
|