Backlog

What backloghq/backlog does

The backloghq/backlog MCP server gives agents a persistent task store that survives the end of an individual session. It is designed for project work where one agent may create or start a task and another agent later needs to find, inspect, continue, or complete it. Each project can receive its own task data automatically, reducing the chance that unrelated projects share the same backlog.

Tasks can represent pending, active, completed, blocked, scheduled, or deleted work. Records support descriptions, priorities, due dates, projects, tags, dependencies, agent identities, timestamps, annotations, and attached Markdown documents. Documents can hold specifications, implementation context, or handoff notes.

The repository also provides seven Claude Code skills for viewing, planning, refining, specifying, implementing, and handing off work. Its task-planner agent can decompose goals into tasks and write specifications. Hooks connect the backlog with Claude’s built-in task events, including session startup, task creation, completion, and subagent startup.

How it works

The server is implemented in TypeScript and is built on @backloghq/agentdb. Storage uses the filesystem by default and can use Amazon S3 when the S3 backend is selected. In standalone mode, TASKDATA identifies the data directory or, with S3, the key prefix. Plugin usage can derive project-specific storage automatically; explicit namespaces are also available.

Multiple processes can share a backlog. Each process can set a distinct BACKLOG_AGENT_ID, allowing separate write logs instead of relying on file locks. Operations refresh data before use so changes from other agents can be picked up. Namespaces can be set manually or derived from the current working directory.

Filtering supports fields such as status, project, priority, due date, description, and agent. It also supports tags, virtual states such as +ACTIVE, +BLOCKED, +READY, and +OVERDUE, attribute modifiers, and Boolean expressions.

Setup and configuration

The backloghq/backlog MCP server can be installed as a Claude Code plugin with /plugin marketplace add backloghq/backlog, followed by /plugin install backlog@backloghq-backlog. From source, the documented flow is to clone the repository, run npm install, build it, and point Claude at the resulting plugin directory.

For standalone use, configure an MCP entry that runs the built dist/index.js file with Node. Set TASKDATA to a data directory, or configure BACKLOG_BACKEND as s3 with BACKLOG_S3_BUCKET and an optional BACKLOG_S3_REGION. S3 storage additionally requires the @backloghq/opslog-s3 package. BACKLOG_NAMESPACE and BACKLOG_AUTO_NAMESPACE control collection naming.

Tools and capabilities

The MCP tools cover the full task lifecycle:

• Query and count tasks with filter expressions.
• Create, import, duplicate, modify, start, stop, complete, delete, undo, and permanently purge tasks.
• Add or remove timestamped annotations.
• Write, read, replace, and delete Markdown task documents.
• Archive completed or deleted tasks and inspect archive segments.
• List projects and tags that contain pending or recurring tasks.

Deletion is soft by default, while purging and deleting an attached document are permanent operations. Bulk import is atomic, and task_info returns complete details for a task identified by ID or UUID.

Limitations and notes

The documented standalone configuration uses a built JavaScript file path, so the project must be built from source before that mode can run. S3 is optional rather than the default and requires an additional package plus bucket configuration. Permanent purge and document deletion cannot be reversed. The README documents Claude Code skills and hooks; the MCP tools can also be used by other compatible MCP clients when configured as a standalone server.

Getting started with this backloghq/backlog MCP server

Always refer to the official documentation for the most accurate and up-to-date information.