Beads
by steveyegge
Beads-MCP exposes Steve Yegge's graph-based issue tracker as MCP tools, giving a coding agent durable, dependency-aware memory across sessions.
About
Beads models tasks as a dependency graph instead of a flat list: dep records blocking and parent-child relationships between issues, and ready / blocked query the graph to tell an agent exactly which issues are actually unblocked right now versus stuck waiting on something else. create, update, close, and reopen manage the issue lifecycle, while comment and note leave a timestamped record of decisions the agent can re-read in a later session instead of re-deriving context from scratch.
beads-mcp is specifically the MCP-only path into this system. For shell-capable clients like Claude Code, the project recommends the bd CLI plus hooks instead, since MCP is meant to cover environments like Claude Desktop where there's no shell access. It supports multiple projects from one server instance, routing each workspace to its own backing store.
Key features
- dep models blocking and parent-child relationships as a real dependency graph, not a flat list
- ready and blocked tell an agent exactly which issues are unblocked versus stuck right now
- comment and note leave a timestamped audit trail of decisions the agent can re-read later
- Multi-project support routes each workspace to its own backing store automatically
- Positioned as the MCP-only alternative to Beads' CLI+hooks integration for shell-capable agents
Use cases
- Giving a coding agent persistent memory of open work that survives a context reset or new session
- Tracking a real dependency graph of blocking issues instead of a markdown checklist that goes stale
- Recording decisions and rationale as timestamped notes an agent can query later instead of re-asking
- Running Beads inside an MCP-only client like Claude Desktop where there's no shell access for the CLI
Available tools
create
Creates a new issue in the tracker.
ready
Lists issues that are unblocked and ready to work on.
blocked
Lists issues that are currently blocked on a dependency.
dep
Manages dependency relationships between issues, including blocking and parent-child links.
comment
Adds a timestamped comment to an issue.
close
Closes an issue, marking it resolved.
Frequently asked questions
Should I use the MCP server or the CLI?
Use the bd CLI plus hooks if your client has shell access, like Claude Code. Use beads-mcp for MCP-only clients such as Claude Desktop that can't run a CLI directly.
How is this different from a markdown TODO file?
Issues live in a real dependency graph with blocking and parent-child edges, so ready/blocked can tell an agent exactly what's actionable instead of it re-reading a flat list every time.