使用说明
backlog-mcp
A local-first, Markdown-backed engine for agent context and memory. Tasks, decisions and memories share one store across MCP clients, the CLI and a live read-only viewer. Humans can read, edit and diff the files directly.
Entities are Markdown with YAML frontmatter. A project’s substrate declarations own its types, fields and workflows. Local hybrid search combines text and embeddings; progressive disclosure keeps orientation small and expands content when the agent needs it.
Install
Requires Bun 1.4.2 or newer.
Add this to .mcp.json or your MCP client configuration:
{
"mcpServers": {
"backlog": {
"command": "bunx",
"args": ["--bun", "backlog-mcp"]
}
}
}
For agent-assisted setup, ask your agent to read and follow the installation skill. The default command starts a persistent local HTTP server and bridges MCP stdio requests to it. See installation and server lifecycle.
Quick start
From your project directory, explicitly select its home (even without docs/ yet):
bunx --bun backlog-mcp --home project --project-root . wakeup
bunx --bun backlog-mcp --home project --project-root . create "Fix authentication flow" --content "Investigate the failing login."
bunx --bun backlog-mcp --home project --project-root . list --type task
bunx --bun backlog-mcp --home project --project-root . recall "authentication decisions"
bunx --bun backlog-mcp --home project --project-root . remember "Describe one verified durable login convention." --title "Login convention" --layer semantic
For MCP task work, discover and inspect the full schemas of
backlog_create_work, backlog_start_task and backlog_complete_task.
The Markdown body field is content; declarations may add required fields.
Wake up once at session start. Recall when prior knowledge matters, inspect its
age and correction lineage, then expand selected entities with backlog_get
(context: true includes relation stubs). Remember one durable fact per memory;
correct an old fact with supersedes or state_key.
See the memory protocol.
Viewer
Open localhost:3030 while the server is running. The Desk surfaces at most seven attention items with provenance and copy-ready instructions for your agent. The viewer provides search, entity detail, activity and live updates; edits flow through your agent or native Markdown files. See viewer usage.
Documentation
- Documentation map: users, contributors and historical decisions.
- Commands and entities.
- Homes, configuration and migration.
- Claude Code session hooks.
- Development, testing and releases.
- ADR index and product direction.
Local Markdown remains the source of truth. Legacy Workers/D1 hosting is retained and descoped; see the installation guide.
MIT licensed. npm package · Maintainer’s engineering story.
