MCP Backlog Server

You can manage backlog items and their subtasks with a dedicated MCP server that tracks work items, their statuses, priorities, and completion through markdown-backed records. This server keeps items organized across projects and makes it easy for your MCP client to query, update, and archive work as your team progresses from new ideas to done work.

How to use

You connect your MCP client to the backlog server by configuring an MCP server entry that points to a local process or a running MCP endpoint. You can run the backlog server locally using a command-line runner or start it from a build artifact, then point your client to that instance. The server supports creating backlog items, listing them, updating status, and managing related todos with dependency checks. Use the included workflow to progress items from new to ready, review, and done, or reopen/wontfix when needed.

How to install

Prerequisites: Node.js and npm or a Bun-compatible runtime. Choose a quick-start method or install globally and run the server.

# Quick Start (Zero Install) with NPX
npx -y github:rwese/mcp-backlog

# Quick Start with Bunx (Bun - Faster)
bunx --bun github:rwese/mcp-backlog

Further installation methods

Global installation and from-source options let you run the backlog server as a standard command or build from source for a customized setup.

# Global Install with Bun (recommended)
bun add -g github:rwese/mcp-backlog

# Global Install from NPM
bun add -g @rwese/mcp-backlog

# From NPM
npm install -g github:rwese/mcp-backlog
npm install -g @rwese/mcp-backlog

From Source

git clone https://github.com/rwese/mcp-backlog.git
cd mcp-backlog
bun install  # or npm install
bun run build  # or npm run build

Configure the MCP client

In your MCP client configuration, define one or more backlog MCP servers. The following examples show how to wire a backlog server using different runtimes. Each entry is an MCP server configuration you can place in your client’s configuration file.

Example configurations

{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": ["-y", "github:rwese/mcp-backlog"]
    }
  }
}

{
  "mcpServers": {
    "backlog": {
      "command": "bunx",
      "args": ["--bun", "github:rwese/mcp-backlog"]
    }
  }
}

{
  "mcpServers": {
    "backlog": {
      "command": "mcp-backlog"
    }
  }
}

{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": ["@rwese/mcp-backlog"]
    }
  }
}

{
  "mcpServers": {
    "backlog": {
      "command": "node",
      "args": ["/path/to/mcp-backlog/dist/index.js"]
    }
  }
}

Storage and environment configuration

Backlog data is stored in XDG-compliant directories with multi-project isolation by default. You can override storage locations with environment variables. For example, set MCP_BACKLOG_DIR to a custom path or set XDG_DATA_HOME to relocate all XDG-compliant data.

export MCP_BACKLOG_DIR="/custom/path"

export XDG_DATA_HOME="/path/to/data"
# Backlog will be stored at: /path/to/data/mcp-backlog/

Workflow

• Create a backlog item with status "new"
• Submit to move it to "ready" (ready for work)
• Amend to update status to "review" when work is done
• Approve to move from "review" to "done"
• Done to archive the completed item
• Or reopen to send items back for more work, or set to wontfix to archive without completing

Available tools

backlog-read

List and filter backlog items by status or priority.

backlog-write

Create and manage backlog items with actions like create, list, amend, approve, submit, reopen, wontfix.

backlog-done

Mark backlog items as complete and manage their overall lifecycle.

backlog-todo-read

List todos for a backlog item and filter by status or batch.

backlog-todo-write

Create, update, or list todos within backlog items and manage dependencies.

backlog-todo-done

Mark todos as complete with dependency validation.