GitHub Copilot Integration

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

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

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": []
    }
  }
}

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.

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)

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.

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

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

Get Started

Core Concepts

Guides

Integrations

GitHub Copilot Integration

Prerequisites

Quick Setup

MCP Tools Reference

Example Workflow

Finding Work

Claiming an Issue

Completing Work

CLI vs MCP: When to Use Each

Troubleshooting

MCP tools not appearing in Copilot

”beads-mcp: command not found”

“No beads database found”

Changes not persisting

Organization policies blocking MCP

FAQ

See Also

MCP Server Details

CLI Reference

Claude Code

Aider Integration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Integrations

​Prerequisites

​Quick Setup

​MCP Tools Reference

​Example Workflow

​Finding Work

​Claiming an Issue

​Discovering Related Work

​Completing Work

​CLI vs MCP: When to Use Each

​Troubleshooting

​MCP tools not appearing in Copilot

​”beads-mcp: command not found”

​“No beads database found”

​Changes not persisting

​Organization policies blocking MCP

​FAQ

​See Also

MCP Server Details

CLI Reference

Claude Code

Aider Integration

Build docs developers (and LLMs) love

Prerequisites

Quick Setup

MCP Tools Reference

Example Workflow

Finding Work

Claiming an Issue

Discovering Related Work

Completing Work

CLI vs MCP: When to Use Each

Troubleshooting

MCP tools not appearing in Copilot

”beads-mcp: command not found”

“No beads database found”

Changes not persisting

Organization policies blocking MCP

FAQ

See Also