backlog-mcp

backlog-mcp is an MCP (Model Context Protocol) server that provides AI agents with structured read and write access to story-based project backlogs. Agents can list stories, read content, update status, and append notes, with all data stored in plain Markdown files within the project repository.

Purpose

This project is designed to enable AI agents to handle project backlogs much like they handle code. Backlog files are stored in the repository's requirements/ directory and are committed and version-controlled alongside the code. Collaboration works the same way as with a codebase: through git. If two agents concurrently update different stories, git merges them; if they modify the same line, it is resolved like any other merge conflict. There is no shared server; the MCP server is a local process run by each agent itself, it reads and writes files, and git handles the rest.

Main capabilities

• List stories, read story content, update story status, and append notes.
• Support creating a plan file, generating a plan scaffold in the requirements/ directory.
• Provide operations such as set_epic_status and complete_story, with guards to ensure the process is correct.
• Include an automated PR backlog agent (GitHub Actions workflow) that automatically updates story status and appends notes when a pull request is opened or updated, with no API key required, using only the standard GITHUB_TOKEN.
• Support MCP client configurations such as VS Code / GitHub Copilot and Claude Code.

Usage

1. Installation: You can download the binary for your platform from the Releases page and place it in $PATH; if Go is installed, you can install it with go install github.com/corbym/backlog-mcp@latest; you can also build it from source.
2. Initialization: Create a requirements/ folder in the project root and commit it to the repository. Edit the files to add your own epics and stories.
3. The server looks for the requirements/ directory relative to the working directory at startup. Claude Code sets the working directory to the project root, soThis requires no configuration.
4. Configure the MCP client: it is recommended to use a local configuration file committed to the project root directory, for example VS Code / GitHub Copilot uses .vscode/mcp.json, and Claude Code uses .claude/settings.json. A global configuration can serve as a fallback.
5. When using GitHub Copilot agent mode, MCP tools are only available in Agent mode; switch via the mode dropdown menu in Copilot Chat. After configuration, the Copilot agent can call all to-do tools such as list_stories, get_story, add_story_note, etc. in a chat session.

Applicable Scenarios

Suitable for teams or individuals who want to tightly integrate project to-dos with the code repository and use git for collaboration and version control. Especially suitable for scenarios that use AI agents for development process management, such as having the agent automatically update story status, update to-dos based on PRs, etc.

Limitations

• File writes are atomic (temporary file + rename); a crash will not corrupt the file.
• The file system is the single source of truth; the MCP server never owns the data.
• Setting an epic status to done requires providing a summary (completion note), and all stories must be completed; otherwise the call fails and lists the incomplete stories. Only when the user explicitly confirms that incomplete stories can be ignored may override_incomplete=true be passed.
• Status rollback (such as done → in-progress) triggers a regression prompt; the agent should suggest creating a new story, and only when the user explicitly insists on skipping may confirm_regression=true be passed. blocked and deferred are horizontal statuses and can be set freely.
• Before completing a story, acceptance criteria must be set (not the default placeholder); unchecked acceptance criteria will prevent completion unless incomplete_items is provided with an explanation for each unchecked item. Completed criteria should first be checked via set_acceptance_criteria; do not use incomplete_items to confirm work that has actually been completed.
• Story types: feature, bug, chore, spike. Status values: draft, in-progress, done, blocked, deferred.
• Story files are located under BACKLOG_ROOT at epic-NNN-slug/story-NNN.md.
• The automated PR workflow scans PR titles and branch names for STORY-NNN IDs, and after matching sets the status and appends a note, then commits the changes back to the PR branch.
• Branch and PR naming must include the STORY-NNN ID; see CONTRIBUTING.md for the specific conventions.

Information Not Yet Provided

Specific details about fees, pricing, platform support, performance data, etc. are not yet provided in the materials.