backlog-mcp

An MCP (Model Context Protocol) server for Backlog (Nulab), providing AI agents with read access to Backlog issues and comments via API Key authentication.

Stack

• TypeScript — strict, ESM (NodeNext)

• @modelcontextprotocol/sdk — MCP server + stdio transport

• Zod — config and tool input validation

• Axios — Backlog REST API HTTP client

Features

• 🔑 Simple API Key authentication (no browser or SSO required)

• 🔎 backlog_get_issue_list — list issues with rich filtering (project, status, priority, assignee, keyword, etc.)

• 🔍 backlog_get_issue — fetch a single issue's full details

• 💬 backlog_get_comments — fetch issue comments with changelog entries

• 🗂️ backlog_get_projects — list all accessible projects (with IDs and keys for filtering)

• 👥 backlog_get_users — list project members (get user IDs for assignee filtering)

• 📎 backlog_get_attachments — list attachments on an issue (with IDs for downloading)

• ⬇️ backlog_download_attachment — download an attachment to the local filesystem

• 📦 backlog_export_issue_context — export issue, comments, and attachments into a local raw Markdown context bundle for LLM summarization

• 🏷️ backlog_get_statuses — list all statuses in a project (with IDs for filtering)

• ⚡ backlog_get_priorities — list global issue priorities (with IDs for filtering)

• 📂 backlog_get_categories — list all categories in a project (with IDs for filtering)

• 🎯 backlog_get_milestones — list milestones/versions in a project (with IDs for filtering)

Requirements

• Node.js >= 20

• A Backlog space with API access

• A Backlog API Key (generate at Account Settings → API → Register API key)

Quick Start (End Users)

No cloning or building required. Uses npx directly — the MCP client spawns and manages the process automatically via stdio.

Step 1 — Add to your MCP client

Gemini CLI

gemini mcp add backlog npx -y @cuongph.dev/backlog-mcp --env BACKLOG_BASE_URL=https://yourspace.backlog.com --env BACKLOG_API_KEY=your_api_key_here

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project:

{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": ["-y", "@cuongph.dev/backlog-mcp"],
      "env": {
        "BACKLOG_BASE_URL": "https://yourspace.backlog.com",
        "BACKLOG_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": ["-y", "@cuongph.dev/backlog-mcp"],
      "env": {
        "BACKLOG_BASE_URL": "https://yourspace.backlog.com",
        "BACKLOG_API_KEY": "your_api_key_here"
      }
    }
  }
}

Tip: You can omit the env block and place the variables in a .env file at your working directory instead. dotenv is loaded automatically at startup.

Restart your MCP client after saving the config. No separate server process needed — the client spawns and manages it automatically.

Development Setup

For contributors and developers working on the source code.

1. Clone and install

git clone <repo-url>
cd backlog-mcp
npm install

2. Configure environment

cp .env.example .env

Edit .env:

BACKLOG_BASE_URL=https://yourspace.backlog.com
BACKLOG_API_KEY=your_api_key_here

3. Add to MCP client (local build)

First build the project:

npm run build

Then use the local dist/server.js in your MCP config:

Cursor (~/.cursor/mcp.json):

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

The .env file in the project root is loaded automatically — no need to duplicate env vars in the MCP config.

Agent Summary Prompt

After exporting an issue with backlog_export_issue_context, use docs/prompts/backlog_issue_summary.md as the agent prompt template for summarizing task intent, comments, attachments, inferred acceptance criteria, and optional code context.

For Backlog-to-Jira migration, use docs/prompts/backlog_to_jira_migration.md. It keeps Jira description short, posts raw Backlog context, Vietnamese translation, and Vietnamese analysis as separate Jira comments, and uploads matching markdown files with clear names.

MCP Tools

backlog_get_issue_list

Fetch a list of Backlog issues with optional filters.

Input:

Output: Compact table + detailed summaries for each issue (key, type, status, priority, assignee, dates, hours).

backlog_get_issue

Fetch a single Backlog issue by key or numeric ID.

Input:

Output: Full issue details — summary, description, status, priority, type, assignee, reporter, categories, milestones, versions, dates, estimated/actual hours, URL.

backlog_get_comments

Fetch comments for a Backlog issue.

Input:

Output: List of comments with author, date, text content, and field changes (changelog).

backlog_get_projects

Fetch the list of Backlog projects accessible to the current API Key.

Input:

Output: Table of projects with ID, key, name, and archived flag. Use the key in project-scoped tools or projectIdOrKey in backlog_get_issue_list.

backlog_get_users

Fetch project members for a given Backlog project.

Input:

Output: Table of project members with numeric ID, userId, name, email, and role. Use the ID as assigneeId in backlog_get_issue_list.

backlog_get_statuses

Fetch all statuses defined for a Backlog project.

Input:

Output: Table of statuses with ID, name, and color. Use IDs in statusId filter of backlog_get_issue_list.

backlog_get_priorities

Fetch the global list of issue priorities (space-wide, not project-specific).

Input: None required.

Output: Table of priorities with ID and name. Use IDs in priorityId filter of backlog_get_issue_list.

backlog_get_categories

Fetch all categories defined for a Backlog project.

Input:

Output: Table of categories with ID and name. Use IDs in categoryId filter of backlog_get_issue_list.

backlog_get_milestones

Fetch milestones (versions) for a Backlog project.

Input:

Output: Table of milestones with ID, name, start date, due date, and archived flag. Use IDs in milestoneId filter of backlog_get_issue_list.

Project Structure

src/
├── server.ts                # MCP server entry point (factory pattern + Express)
├── config.ts                # Env var validation (Zod)
├── errors.ts                # Typed error classes & factories
├── utils.ts                 # Shared helpers (dates, string formatting)
├── types.ts                 # Normalized domain types (BacklogIssue, BacklogComment, ...)
├── types/
│   └── backlog-api.ts       # Raw Backlog API response types
├── backlog/
│   ├── endpoints.ts         # URL builders (API v2)
│   ├── mappers.ts           # Raw API payload → domain types
│   └── http-client.ts       # API Key-authenticated Backlog HTTP client
├── tools/
│   ├── get-issue-list.ts    # backlog_get_issue_list handler
│   ├── get-issue.ts         # backlog_get_issue handler
│   ├── get-comments.ts      # backlog_get_comments handler
│   ├── get-statuses.ts      # backlog_get_statuses handler
│   ├── get-priorities.ts    # backlog_get_priorities handler
│   ├── get-categories.ts    # backlog_get_categories handler
│   └── get-milestones.ts    # backlog_get_milestones handler
└── tests/                   # Unit tests (Vitest)

Development Commands

# Type check (no emit)
npx tsc --noEmit

# Run tests
npm test

# Watch mode
npm run test:watch

# Build for production
npm run build

# Run dev server
npm run dev

Error Codes

Security Notes

• .env is git-ignored and must never be committed.

• Your API Key grants full access to your Backlog space as the associated user — treat it like a password.

• The API Key is only stored locally in .env and sent as a query parameter over HTTPS.