GitHub Copilot Integration

Use Beads with GitHub Copilot through MCP for natural language issue tracking

Beads provides an MCP (Model Context Protocol) server that enables GitHub Copilot to manage issues through natural language commands in VS Code.

Beads is a system-wide CLI tool. Install it once and use it in any project. Do NOT clone the beads repository into your project.

Prerequisites

• VS Code 1.96 or later
• GitHub Copilot extension
• GitHub Copilot subscription (Individual, Business, or Enterprise)
• Beads CLI installed
• Python 3.10+ or uv package manager

Quick Setup

1. Install beads-mcp

   Install the MCP server using uv (recommended):

   uv tool install beads-mcp
   

   Alternative installation methods:

   # Using pip
   pip install beads-mcp
   
   # Using pipx
   pipx install beads-mcp
   
2. Configure VS Code MCP

   Create or edit .vscode/mcp.json in your project:

   {
     "servers": {
       "beads": {
         "command": "beads-mcp"
       }
     }
   }
   

   Configure for all projects

   To use Beads across 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": []
       }
     }
   }
   
3. Initialize Beads in your project

   Navigate to your project and initialize Beads:

   cd your-project
   bd init --quiet
   

   This creates a .beads/ directory with the issue database.

4. Add Copilot instructions (optional)

   Create .github/copilot-instructions.md to teach Copilot about Beads:

   ## Issue Tracking
   
   This project uses **bd (beads)** for issue tracking.
   Run `bd prime` for workflow context.
   
   **Quick reference:**
   - `bd ready` - Find unblocked work
   - `bd create "Title" --type task --priority 2` - Create issue
   - `bd close <id>` - Complete work
   - `bd sync` - Sync with git (run at session end)
   
5. Restart VS Code

   Reload the VS Code window for MCP configuration to take effect:

   • Press Cmd/Ctrl + Shift + P
   • Type “Reload Window”
   • Press Enter

MCP Tools Reference

With MCP configured, ask Copilot Chat to perform these operations:

Tool	Description	Example Query
beads_ready	List unblocked issues	”What issues are ready to work on?”
beads_list	List issues with filters	”Show all open bugs”
beads_create	Create new issue	”Create a task for refactoring”
beads_show	Show issue details	”Show bd-42 details”
beads_update	Update issue fields	”Set bd-42 to in progress”
beads_close	Close an issue	”Complete bd-42”
beads_sync	Sync to git	”Sync my changes”
beads_dep_add	Add dependency	”bd-99 blocks bd-42”
beads_dep_tree	Show dependency tree	”What depends on bd-42?”

Example Workflow

Finding Work

You: What issues are ready to work on?

Copilot: [Calls beads_ready]
There are 3 issues ready:
1. [P1] bd-42: Fix authentication timeout
2. [P2] bd-99: Add password reset flow
3. [P3] bd-17: Update API documentation

Claiming an Issue

You: Let me work on bd-42. Claim it.

Copilot: [Calls beads_claim]
Claimed bd-42 and started work.

Discovering Related Work

You: I found a related bug - the session token isn't being refreshed.
     Create a bug for that, linked to bd-42.

Copilot: [Calls beads_create]
Created bd-103: Session token not refreshed
Linked as discovered-from bd-42.

Completing Work

You: Done with bd-42. Close it with reason "Fixed timeout handling"

Copilot: [Calls beads_close]
Closed bd-42: Fixed timeout handling

You: Sync everything to git

Copilot: [Calls beads_sync]
Synced: 2 issues updated, committed to git.

CLI vs MCP: When to Use Each

Approach	Best For	Trade-offs
MCP (Copilot Chat)	Natural language, discovery	Higher token overhead (~10-50k)
CLI (Terminal)	Scripting, precision, speed	Requires terminal context (~1-2k)

You can use both! MCP for conversational work in Copilot Chat, CLI for quick terminal commands.

Troubleshooting

MCP tools not appearing in Copilot

Check VS Code version

MCP requires VS Code 1.96 or later:

code --version

Verify mcp.json syntax

Ensure your JSON is valid:

# macOS/Linux
cat .vscode/mcp.json | python -m json.tool

# Windows
type .vscode\mcp.json | python -m json.tool

Check beads-mcp installation

Verify the MCP server is installed and in PATH:

which beads-mcp
beads-mcp --version

Reload VS Code window

MCP configuration requires a window reload. Press Cmd/Ctrl + Shift + P, type “Reload Window”, and press Enter.

Check Output panel

Open the Output panel in VS Code and look for MCP-related errors:

• View → Output
• Select “MCP” from the dropdown

”beads-mcp: command not found”

The MCP server isn’t in your PATH:

# If installed with uv
export PATH="$HOME/.local/bin:$PATH"

# If installed with pip, find it
pip show beads-mcp | grep Location

# Reinstall if needed
uv tool install beads-mcp --force

“No beads database found”

Initialize Beads in your project:

cd your-project
bd init --quiet

Changes not persisting

Run sync at end of session:

bd sync

Or ask Copilot: “Sync my beads changes to git”

Organization policies blocking MCP

For Copilot Enterprise, your organization must enable “MCP servers in Copilot” policy. Contact your admin if MCP tools don’t appear.

FAQ

Do I need to clone the beads repository?

No. Beads is a system-wide CLI tool. You install it once (via Homebrew, npm, or pip) and use it in any project. The .beads/ directory in your project only contains the issue database, not beads itself.

What are the git hooks and are they safe?

When you run bd init, beads can install git hooks that:

• post-merge: Import issues when you pull
• pre-push: Sync issues before you push

These hooks are safe—they only read/write the .beads/ directory and never modify your code. You can opt out with bd init --no-hooks or skip them during interactive setup.

Can I use beads without Copilot?

Yes! Beads works with:

• Terminal (direct CLI)
• Claude Code
• Cursor
• Aider
• Any editor with MCP or shell access

MCP vs CLI - which should I use?

Use MCP when you want natural language interaction through Copilot Chat. Use CLI when you want speed, scripting, or precise control.

Both approaches work with the same database—use whichever fits your workflow.

Does this work with Copilot in other editors?

This guide is for VS Code. For other editors:

• JetBrains IDEs: Check if MCP is supported, config may differ
• Neovim: Use CLI integration instead

See Also

MCP Server Details

Deep dive into MCP server architecture

CLI Reference

Learn Beads command-line interface

Claude Code

Integrate with Claude Code using hooks

Aider Integration

Use Beads with Aider AI pair programming