MCP — Backlog

On this page

How it works
Workspace resolution
Claude Code
Cursor
Codex (OpenAI)
OpenCode
Available tools
Verifying the connection

How it works

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external tools. Instead of constructing CLI invocations, an MCP server exposes named tools over JSON-RPC 2.0 on stdin/stdout. The AI calls tools by name with structured arguments.

Backlog's MCP server lets any compatible AI assistant read and write your backlog directly — creating tasks, attaching plans, moving status, leaving comments — without any prompt engineering around command syntax.

backlog mcp serve --as ai:claude-code --db /path/to/backlog.db

The process speaks newline-delimited JSON-RPC 2.0 over stdin/stdout. The AI tool spawns it and communicates over its stdio. The server stays alive until the parent closes the pipe.

--as sets the actor for all write operations. Set this so writes are attributed correctly. Defaults to human:$USER if omitted.

Workspace resolution

The MCP server uses the same DB resolution chain as the CLI:

Priority	Source
1	`--db <path>` flag
2	`--profile <name>` flag
3	`BACKLOG_DB` environment variable
4	Walk up from cwd looking for `backlog.db`
5	Default profile (`backlog profile set-default`)

ℹ Using BACKLOG_DB in the MCP config is the most reliable approach — it bypasses cwd-walking entirely and makes the config portable regardless of where the AI tool spawns the process.

Claude Code

CLI method (recommended)

claude mcp add backlog -- backlog mcp serve --as ai:claude-code --db /path/to/workspace/backlog.db

Global config (manual)

~/.claude.json

{
  "mcpServers": {
    "backlog": {
      "command": "backlog",
      "args": ["mcp", "serve", "--as", "ai:claude-code"],
      "env": {
        "BACKLOG_DB": "/path/to/workspace/backlog.db"
      }
    }
  }
}

Project-scoped

.claude/settings.json (repo root)

{
  "mcpServers": {
    "backlog": {
      "command": "backlog",
      "args": ["mcp", "serve", "--as", "ai:claude-code"],
      "env": {
        "BACKLOG_DB": "${workspaceFolder}/backlog.db"
      }
    }
  }
}

Cursor

Place the config at ~/.cursor/mcp.json for global access, or .cursor/mcp.json at the project root for per-project scope.

~/.cursor/mcp.json

{
  "mcpServers": {
    "backlog": {
      "command": "backlog",
      "args": ["mcp", "serve", "--as", "ai:cursor"],
      "env": {
        "BACKLOG_DB": "/path/to/workspace/backlog.db"
      }
    }
  }
}

✦ If backlog is not on your PATH, use the full binary path: "/usr/local/bin/backlog".

Codex (OpenAI)

Codex CLI reads MCP server configuration from ~/.codex/config.yaml.

~/.codex/config.yaml

mcp_servers:
  backlog:
    command: backlog
    args:
      - mcp
      - serve
      - "--as"
      - "ai:codex"
    env:
      BACKLOG_DB: /path/to/workspace/backlog.db

To scope to a single project, create .codex/config.yaml at the repo root with the same structure.

OpenCode

OpenCode reads MCP configuration from opencode.json at the project root, or from ~/.config/opencode/config.json for global config.

opencode.json

{
  "mcp": {
    "backlog": {
      "type": "local",
      "command": "backlog",
      "args": ["mcp", "serve", "--as", "ai:opencode"],
      "env": {
        "BACKLOG_DB": "/path/to/workspace/backlog.db"
      }
    }
  }
}

Available tools

Once connected, the AI assistant has access to the following tools. Task IDs accept TASK-N, bare integer, or full ULID. Plan/doc/memory IDs are ULIDs only.

Tool	Description	Required args
`project_list`	List all projects	—
`task_create`	Create a new task	`project`, `title`
`task_list`	List tasks with filters	—
`task_show`	Show full task detail including plans and comments	`id`
`task_update`	Update task fields	`id`
`task_move`	Transition task status	`id`, `status`
`plan_add`	Attach a plan to a task (creates v1)	`task_id`, `title`, `body`
`plan_update`	Revise a plan (creates new version)	`plan_id`, `title`, `body`
`plan_history`	Retrieve all versions of a plan	`plan_id`
`comment_add`	Add a comment to a task	`task_id`, `body`
`memory_add`	Add a memory entry to a project	`project`, `body`
`memory_list`	List memory entries for a project	`project`
`doc_add`	Create a versioned project doc	`project`, `title`, `body`
`doc_list`	List docs for a project	`project`
`doc_show`	Show a doc's current content	`id`
`doc_update`	Revise a doc (creates new version)	`id`, `body`

task_create — optional fields

Field	Type	Values
`description`	string	Markdown body
`type`	string	`task` · `bug` · `issue` · `improvement` · `feature` · `vulnerability` · `chore` · `spike`
`status`	string	`todo` · `doing` · `done`
`priority`	integer	`1` (critical) through `5` (backlog)
`source`	string	Origin system, e.g. `security-review`
`external_ref`	string	URL or external ticket ID

task_list — filter fields

Field	Type	Description
`project`	string	Project alias
`status`	string	`todo` · `doing` · `done`
`type`	string	Task type filter
`priority`	integer	Exact priority match
`search`	string	FTS5 full-text search query

Verifying the connection

Send the MCP handshake manually to confirm the server starts correctly:

Command

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}' \
  | backlog mcp serve --db /path/to/backlog.db

Expected response

{"jsonrpc":"2.0","id":1,"result":{"capabilities":{"tools":{"listChanged":false}},"protocolVersion":"2024-11-05","serverInfo":{"name":"backlog","version":"1.0.0"}}}