Beadhive

What Beadhive MCP server does

Beadhive MCP server exposes Beadhive operations to an MCP-compatible agent through bh-mcp. Its supported scope is centered on three areas: managing beads work across repositories, checking hive status, and driving Beadhive workflows. The underlying bh command acts as an orchestrator for repositories that participate in a Beadhive workspace.

Each repository is treated as a hive with its own beads database and a short stable prefix. Beadhive can aggregate those hives into a cross-repository view, including hives whose code is not currently checked out. This makes the MCP interface relevant for agents working across several repositories with separate issue stores.

How it works

The MCP process works alongside the bh CLI rather than replacing the systems that bh coordinates. The CLI routes operations across bd, git, git-workspace, dolt, and Docker, while keeping shared configuration and runtime state under ~/.beadhive/.

Issue data is not stored in that configuration directory. Each hive keeps its issues in a Dolt database under refs/dolt/data on that repository's Git remote. As a result, the agent-facing view can span repositories while the underlying issue data remains associated with its own hive.

Setup and configuration

The project provides bh-mcp as part of the Beadhive installation. The documented managed installation uses Nix to install pinned supporting tools, followed by uv tool install --force 'beadhive[otel]' for the Beadhive package. A PyPI-based route using uv, pipx, or Homebrew is also documented, but that route does not install the supporting tools for you.

After installation, initialize Beadhive configuration with bh config init. The README shows bh mcp install as the command used to register the MCP integration with Claude Code at user scope. A local HQ can then be initialized with bh hq init, and repositories can be registered with bh hive onboard <provider>/<org>/<repo>.

Beadhive MCP server depends on a working Beadhive setup and the tools that bh drives. Run bh setup check to identify missing dependencies, or use bh setup guide for a probe-first setup process.

Tools and capabilities

The material describes the MCP interface by its workflows rather than publishing an individual tool catalog. Its documented capability areas are:

• Managing beads work across multiple repositories.
• Viewing the status of registered hives.
• Running Beadhive workflows through the bh ecosystem.
• Working with an aggregated cross-repository view.
• Reaching hives that are registered but not checked out locally.

The broader CLI also supports commands for onboarding hives, checking ready work, initializing configuration, and setting up local HQ. The exact MCP tool names and argument schemas are not specified in the supplied material.

Limitations and notes

Beadhive is not a standalone issue tracker. Its orchestration layer expects the supporting bd, Git, Git workspace, Dolt, and Docker components described by the project. Installation method affects whether those dependencies are version-pinned or must be maintained separately.

A local-only HQ has no backup and is not connected to a second machine until a remote is configured. Configuration and runtime state live under ~/.beadhive/, while issue records remain in each hive's Dolt data on its Git remote. The README specifically documents MCP installation for Claude Code; it does not provide enough information to confirm support for other MCP clients or to describe a complete MCP tool schema.