beads/examples/claude-desktop-mcp/README.md

Claude Desktop MCP Server for Beads

Note

: This is a reference implementation showing how to integrate bd with Claude Desktop via MCP (Model Context Protocol).

What This Provides

An MCP server that exposes bd functionality to Claude Desktop, allowing Claude to:

• Query ready work
• Create and update issues
• Manage dependencies
• Track discovered work

Implementation Status

This is a documentation stub showing the intended integration pattern. Full implementation coming soon!

Planned Features

// MCP server will expose these tools to Claude:

// Find ready work
{
  "name": "beads_ready_work",
  "description": "Find issues with no blocking dependencies",
  "parameters": {
    "limit": "number",
    "priority": "number (0-4)",
    "assignee": "string"
  }
}

// Create issue
{
  "name": "beads_create_issue",
  "description": "Create a new issue",
  "parameters": {
    "title": "string",
    "description": "string",
    "priority": "number (0-4)",
    "type": "bug|feature|task|epic|chore"
  }
}

// Update issue
{
  "name": "beads_update_issue",
  "description": "Update issue status or fields",
  "parameters": {
    "id": "string",
    "status": "open|in_progress|blocked|closed",
    "priority": "number",
    "assignee": "string"
  }
}

// Add dependency
{
  "name": "beads_add_dependency",
  "description": "Link issues with dependencies",
  "parameters": {
    "from": "string (issue ID)",
    "to": "string (issue ID)",
    "type": "blocks|related|parent-child|discovered-from"
  }
}

How It Would Work

1. Install the MCP server for Claude Desktop
2. Claude gains access to bd commands
3. During coding sessions, Claude can:
   • Check for ready work: "What should I work on next?"
   • Create issues: "I found a bug, let me track it"
   • Link discoveries: "This is related to the issue we're working on"
   • Update status: "Marking bd-5 as completed"

Example Conversation

User: What's ready to work on?

Claude: Let me check the ready work queue...
[Calls beads_ready_work()]

I found 3 ready issues:
1. bd-12: Fix authentication bug (priority 0, bug)
2. bd-15: Add dark mode toggle (priority 1, feature)
3. bd-18: Update documentation (priority 2, task)

Which would you like to work on?

User: Let's do bd-12

Claude: Great! I'll mark bd-12 as in progress.
[Calls beads_update_issue("bd-12", status="in_progress")]

Let me investigate the authentication code...
[Works on the issue]

I found the bug in auth.js:45 - there's a race condition. While fixing this, I noticed we're also missing rate limiting. Should I track that as a separate issue?

User: Yes please

Claude: [Calls beads_create_issue("Add rate limiting to auth endpoints", type="task", priority=1)]
Created bd-23: Add rate limiting to auth endpoints

[Calls beads_add_dependency("bd-23", "bd-12", type="discovered-from")]
Linked bd-23 as discovered from bd-12

Now I'll complete the auth bug fix...

Implementation Guide

To implement this MCP server:

1. Create a Node.js/TypeScript project
2. Use the MCP SDK: npm install @anthropic/mcp-sdk
3. Implement tool handlers that call bd commands via child_process
4. Register with Claude Desktop's config

Example skeleton:

import { Server } from "@anthropic/mcp-sdk";
import { exec } from "child_process";
import { promisify } from "util";

const execAsync = promisify(exec);

const server = new Server({
  name: "beads",
  version: "1.0.0"
});

// Register ready work tool
server.tool("beads_ready_work", async (params) => {
  const { stdout } = await execAsync(
    `bd ready --json --limit ${params.limit || 10}`
  );
  return JSON.parse(stdout);
});

// Register create issue tool
server.tool("beads_create_issue", async (params) => {
  const { stdout } = await execAsync(
    `bd create "${params.title}" -d "${params.description}" -p ${params.priority} -t ${params.type} --json`
  );
  return JSON.parse(stdout);
});

// ... more tools ...

server.start();

Installation (Future)

# Install the MCP server
npm install -g beads-mcp-server

# Configure Claude Desktop
# Add to ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp-server",
      "args": []
    }
  }
}

# Restart Claude Desktop

Alternative: Direct bd Usage

Until the MCP server is available, you can instruct Claude to use bd directly:

# In your CLAUDE.md or project instructions:

We use Beads (bd) for issue tracking. Available commands:

- `bd ready --json` - Find ready work
- `bd create "title" -p 1 -t bug --json` - Create issue
- `bd update bd-1 --status in_progress --json` - Update status
- `bd dep add bd-2 bd-1 --type discovered-from` - Link issues
- `bd close bd-1 --reason "Done" --json` - Complete work

All commands support --json for parsing. Please use bd to track work during our sessions.

Contributing

Interested in building this MCP server? We welcome contributions!

See CONTRIBUTING.md for guidelines.

See Also

• MCP Documentation
• MCP SDK
• Claude Desktop
• ../python-agent/ - Python implementation pattern