corbym/backlog-mcp

An MCP server that gives AI agents structured read/write access to a story-based project backlog. Agents can list stories, read content, update status, and append notes — all backed by plain markdown files that live inside your project repository.
How collaboration works
There is no shared server. The backlog files live in your repo under requirements/, committed and versioned alongside your code. Collaboration between agents, or between an agent and a human, works exactly the way the rest of your codebase does: through git. If two agents update different stories concurrently, git merges them. If they touch the same line, you resolve it like any other merge conflict.
The MCP server is a local process each agent runs for itself. It reads and writes files; git handles the rest.
---
Install
Homebrew (tap)
You can also install directly without an explicit tap step:
Binary release
Download the latest binary for your platform from the Releases page and put it somewhere on your $PATH.
Go install
If you have Go installed:
---
Build from source
---
Setup
Initialise a requirements/ folder in your project root:
This creates:
Commit the requirements/ folder to your repo. Edit the files to add your own epics and stories.
---
Running
The server looks for a requirements/ directory relative to the working directory it is launched from. Claude Code sets the working directory to the project root, so no configuration is needed.
Create a plan file
Creates a new plan scaffold in the requirements/ directory. Without a name the file is plan.md; with a name it is plan- .md. If the file already exists a numeric suffix is added (plan-002.md, etc.). Open the file and work with your agent to fill it in before creating stories.
Configuring your MCP client
Prefer a **local** config file committed to your project root. This scopes the server to the project and means any agent cloning the repo gets the right setup automatically. Only use a global config if you want backlog-mcp available in every project without per-project configuration.
**VS Code / GitHub Copilot** — add .vscode/mcp.json to your project root:
**Claude Code** — add .claude/settings.json to your project root:
For a global fallback (applies to every project), place the same config in ~/.claude/settings.json (Claude Code) or add it to VS Code's user settings.json under the mcp.servers key (GitHub Copilot). Always prefer the local per-project file.
---
Tools
| Tool | Description |
|------|-------------|
| list_stories | List stories, optionally filtered by epic_id, status, or story_type |
| get_story | Get full markdown content and metadata for a story, including story_type |
| get_index_summary | High-level epic/story counts by status |
| create_epic | Create a new epic — assigns next EPIC-NNN ID, writes epic file, registers in index |
| create_story | Create a new story under an epic — assigns next STORY-NNN ID, registers in index and backlog |
| set_epic_status | Update epic lifecycle status with completion and regression guards (see below) |
| set_story_status | Update story status (draft, in-progress, blocked, deferred) in index and backlog |
| set_acceptance_criteria | Replace the acceptance criteria section of a story (idempotent) |
| check_acceptance_criterion | Tick a single acceptance criterion [x] by index or text |
| add_story_note | Append a timestamped note to a story file |