Backlog MCP Server
Summary: Backlog MCP Server is a local-first, markdown-backed context and memory engine that lets agents track project work and durable knowledge as plain files — list, read, search, create, transition, and recall entities through MCP tools.
Orient at session start —
backlog_wakeupreturns a dense briefing of active tasks, epics, constraints, recent completions, activity, and unfiled work; optionalscopenarrows it to a folder/milestone/epic, andoperationresumes a mid-flight operation as the focus.Recall durable memory —
backlog_recallretrieves memory stubs (facts, procedures, episodes) by hybrid search, with layers, tags, context scoping, and token budgets; expand withbacklog_get.Remember and correct knowledge —
backlog_rememberwrites atomic memories with kind/layer/supersedes/state_key/valid_until;backlog_forgetretracts or GCs expired memories.Maintain memory hygiene —
backlog_consolidation_candidatessurfaces episodic clusters ripe for consolidation;backlog_contradictionsfinds conflicting live beliefs sharing a state_key plus semantic collision candidates.List and browse entities —
backlog_listfilters by type, status, parent, query, with optional counts and limits.Read entities and neighborhoods —
backlog_getfetches by ID, doc path, or MCP URI (batch supported), withcontext:trueanddepthexpanding parent/children/siblings/references as stubs.Search everything —
backlog_searchdoes relevance-ranked hybrid full-text + semantic search across substrates and generic resources, with type/status/parent/sort filters, snippets or full content, and scores.Create and transition declared intents — dedicated verbs for work and lifecycle:
backlog_create_work,backlog_plan_epic,backlog_organize_folder,backlog_target_milestone,backlog_attach_artifact,backlog_schedule_cron,backlog_propose_adr,backlog_capture_requirement,backlog_capture_reference,backlog_capture_prompt.Move work through states —
backlog_start_task,backlog_complete_task(with evidence),backlog_block_task(with reasons),backlog_pause_cron,backlog_resume_cron,backlog_accept_adr,backlog_supersede_adr.Edit existing entity bodies safely —
write_resourcevalidates and canonically persists markdown body edits viastr_replace,insert, orappend.Delete permanently —
backlog_deleteremoves an item.Attribute writes — an optional
asidentity (AGENT- id or principal) is accepted on writes, following the worktree/env/config attribution ladder.Work across homes — every tool accepts
home(global/project/all) andproject_rootto select which markdown store is read or written.Consume outside MCP — the same store is served by a CLI and a read-only real-time web viewer at
http://localhost:3030(with the Desk attention page), plus an HTTP API.
Uses Markdown as the primary storage and data format for task entities, providing tools to create, retrieve, and edit task content through Markdown files.
The web viewer supports rendering Mermaid diagrams within task descriptions for visualizing workflows and architectural decisions.
Utilizes YAML frontmatter within task files to manage structured metadata, including status, IDs, relationships, and custom attributes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Backlog MCP Server list all open tasks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: Task Manager MCP Server
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 semanticFor 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.
Development, testing and releases.
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.
Available Tools
23 toolsbacklog_accept_adrA
Use when ratifying an existing proposed ADR.
Inputs: id (required), as.
backlog_attach_artifactB
Use when attaching an artifact to a project item. parent_id is required.
Inputs: title (required), parent_id (required), as, path, +3 more.
backlog_block_taskC
Use when blocking a task with a reason.
Inputs: id (required), blocked_reason (required), as.
backlog_capture_promptC
Use when preserving a verbatim human directive as a chronological project prompt.
Inputs: title (required), content (required), as, date, +3 more.
backlog_capture_referenceA
Use when recording an external technology, prior-art system, or benchmark this project builds on — with authoritative citations and the project's adopt/park/reject relationship to it.
Inputs: title (required), content (required), bears_on (required), category (required), +4 more.
backlog_capture_requirementC
Use when recording a human or system requirement in the current project.
Inputs: title (required), content (required), as, date, +11 more.
backlog_complete_taskC
Use when completing a task, optionally with evidence.
Inputs: id (required), as, evidence.
backlog_consolidation_candidatesA
List clusters of episodic memories that are ripe for consolidation into durable knowledge. Consolidator workflow: (1) call this and take ripe bundles; (2) per bundle, read members (backlog_get on MEMO- ids for depth), then write ONE narrative memory via backlog_remember({ layer: "semantic"|"procedural", derived: true, entity_refs: [member MEMO- ids + key source entities], context }) — a self-contained story, not fragments; (3) retire the members via backlog_forget({ ids }) so they stop appearing here while staying auditable; (4) track your progress with a backlog_remember state_key like "consolidation.watermark.".
Inputs: home, limit, context, min_count, +4 more.
backlog_contradictionsA
List structural contradictions in memory: sets of ≥2 LIVE memories that share one state_key (e.g. "db.primary"), which should never happen — a new memory with a state_key auto-expires the previous holder. Each set means two beliefs about the same fact are both active. Resolution is yours, never automatic: pick the correct member, then either backlog_remember({ content, state_key, supersedes: }) to record the right value and retire the rest, or backlog_forget({ ids: [] }) to expire the wrong ones. Read members with backlog_get for full context before deciding. Set candidates: true to list semantic collision candidates instead: nearby live facts that deserve review, never contradiction verdicts.
Inputs: home, candidates, project_root.
backlog_create_workB
Use when creating a project work item. Pass parent_id when known; parentless work surfaces as unfiled at wakeup.
Inputs: title (required), as, content, parent_id, +1 more.
backlog_deleteC
Delete an item permanently.
Inputs: id (required), as, home, project_root.
backlog_forgetA
Retract memories — soft-expire them so recall stops returning them (the record stays auditable in the viewer). Use when knowledge is wrong or obsolete and there is no replacement (if there IS a replacement, use backlog_remember with supersedes instead). expired:true garbage-collects already-expired memories.
Inputs: ids, home, layer, context, +3 more.
backlog_getA
Get full details by ID. Accepts task IDs (TASK-0001, EPIC-0002), document paths (README.md, docs/adr/0001-example.md), or MCP resource URIs (mcp://backlog/resources/design.md). Works for any item regardless of status. Pass context:true when starting work on an entity to also see its relational neighborhood as stubs.
Inputs: id (required), home, depth, context, +1 more.
backlog_organize_folderA
Use when creating a folder to organize project items. Pass parent_id when known; parentless work surfaces as unfiled at wakeup.
Inputs: title (required), as, content, parent_id.
backlog_pause_cronB
Use when pausing a scheduled intake.
Inputs: id (required), as.
backlog_recallA
Recall memories — knowledge and episodes captured across sessions. Returns STUBS (title + one-line digest + provenance) by default; expand interesting ones with backlog_get(MEMO-id), or pass full:true for bodies. Weigh a stub's trust BEFORE hydrating: age_days (on the knowledge's own timeline), uses/idle_days (recall demand), supersedes (this is a correction), derived (consolidator inference), kind (current/historical/plan/preference/timeless). Old + never-used = treat as hypothesis, not truth. Distinct from backlog_search (live entities). Use to answer "how do we deploy?", "have I hit this before?", "what did I finish about X?". Memories point back to source entities via entity_id.
Inputs: query (required), full, home, tags, +5 more.
backlog_rememberA
Write a durable memory — a stable fact, a procedure, or a preference you should know next session. Use when you learn something worth keeping: "this repo deploys via wrangler", "Goga prefers terse evidence bullets". To CORRECT existing knowledge, pass supersedes (the old MEMO- id is expired, lineage kept) or state_key (previous holders of the same evolving fact are closed). The optional collision_candidates receipt is tri-state: [] means the advisory scan completed clean; a non-empty array means nearby facts deserve adjudication; absent means the advisory scan did not run or failed, not that the write failed. Do not use for task events — completions are captured automatically.
Inputs: title (required), content (required), as, home, +11 more.
backlog_resume_cronC
Use when resuming a scheduled intake.
Inputs: id (required), as.
backlog_schedule_cronB
Use when scheduling recurring project intake. Pass parent_id when known; parentless work surfaces as unfiled at wakeup.
Inputs: title (required), command (required), schedule (required), as, +3 more.
backlog_searchA
Search across all indexed backlog substrates and generic resources. Returns relevance-ranked results with match context. Use this for discovery; use backlog_list for filtering by status/type.
Inputs: query (required), home, sort, limit, +6 more.
backlog_supersede_adrA
Use when a newer ADR replaces an accepted or living ADR while preserving lineage.
Inputs: superseded_id (required), replacement_id (required), as.
backlog_wakeupA
Dense session-start briefing: active tasks, current epics, project constraints (requirements as stubs, violated/at-risk first — treat these as standing product intent), recent completions (with evidence snippets), recent activity, and the home-wide unfiled work count. No focal entity required — use this at the start of every session to understand what you were working on. Optional scope narrows the entity sections to a folder, milestone, or epic; unfiled remains home-wide because parentless work has no subtree ancestry. Optional operation resumes a mid-flight operation document: its live state becomes the briefing's FOCUS centerpiece and the rest of the briefing yields budget to it.
Inputs: home, scope, operation, max_activity, +4 more.
write_resourceA
Use when you want backlog-mcp to validate and canonically persist an existing entity edit before reporting success. For ordinary repository prose edits, use your native Edit tool; reconciliation updates indexes and diagnostics afterward. Create and transition entities through the substrate-declared intent tools.
The
appendcommand will add content to the end of the body, automatically adding a newline if needed. Notes for using thestr_replacecommand:The
old_strparameter should match EXACTLY one or more consecutive lines from the original body. Be mindful of whitespaces!If the
old_strparameter is not unique in the body, the replacement will not be performed. Include enough context to make it unique.The
new_strparameter should contain the edited lines that should replace theold_str
Inputs: id (required), operation (required), as, home, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Some tools are clearly distinct (backlog_get, backlog_delete, backlog_search), but overlap exists among 'capture' tools (backlog_capture_prompt, backlog_capture_reference, backlog_capture_requirement) and 'create' tools (backlog_create_work, backlog_organize_folder, backlog_schedule_cron) that may confuse selection. Also, backlog_wakeup and backlog_recall both serve retrieval purposes, but their contexts differ; the descriptions do help to differentiate these.
All tool names are lowercase with underscores, but the verb style varies: some use verb_noun (backlog_get, backlog_delete), others use verb_object (backlog_complete_task, backlog_attach_artifact), and some lack a clear verb-object structure (backlog_consolidation_candidates, backlog_contradictions). The consistent prefix 'backlog_' helps, but patterns like 'create' vs 'capture' and 'organize' are not uniform.
23 tools is a fairly large set, but it covers the domain of a project management/knowledge memory server well. Each tool serves a distinct function — CRUD for work items, ADR management, memory operations, scheduling, and organization. Slightly heavy, but justified given the breadth of features (tasks, ADRs, memories, scheduling).
The tool surface is extensive, covering work item lifecycle (create, get, delete, complete, block), ADR handling (accept, supersede), memory management (remember, recall, forget, consolidation), and project organization (folders, attachments, requirements). Minor gaps include no explicit 'update_work' or 'unblock_task', but these may be handled via write_resource or other mechanisms.
Maintenance
Related MCP Connectors
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
A graph-based task manager your agent can read and update: tasks, dependencies, blockers.
AI-native task management: list, create, update and archive tasks with rich context for AI agents
Create, search, and list Changologs logs and tasks
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables users to manage tasks through a simple JSON file interface. Provides basic task management functionality by reading and writing to a configurable tasks.json file.20 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables task management through natural language with full CRUD operations including add, list, update, complete, and delete tasks with JSON persistence.ISC
- FlicenseNot gradedqualityDmaintenanceManages TODO tasks with operations like add, list, complete, update, and delete, stored in a JSON file.-
- AlicenseBqualityDmaintenanceEnables task management via MCP tools for creating, listing, updating, completing, and deleting tasks with JSON file storage.6ISC