# 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

```bash
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:

```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"
      }
    }
  }
}
```

#### Claude Desktop

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

```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

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

### 2. Configure environment

```bash
cp .env.example .env
```

Edit `.env`:

```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:

```bash
npm run build
```

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

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

```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:**
| Field | Type | Description |
|---|---|---|
| `projectIdOrKey` | `string` | Filter by project key ("MYPROJ") or numeric ID ("12345") — comma-separated, auto-resolved |
| `statusId` | `number[] or string` | Filter by status: 1=Open, 2=InProgress, 3=Resolved, 4=Closed. Accept `[1,2]` or `"1,2"` |
| `priorityId` | `number[] or string` | Filter by priority: 2=High, 3=Normal, 4=Low. Accept `[2,3]` or `"2,3"` |
| `assigneeId` | `number[] or string` | Filter by assignee user ID(s). Get IDs from `backlog_get_users` |
| `categoryId` | `number[] or string` | Filter by category ID(s) |
| `milestoneId` | `number[] or string` | Filter by milestone ID(s) |
| `keyword` | `string` | Search keyword in summary and description |
| `parentChild` | `0\|1\|2\|3\|4` | 0=all, 1=child only, 2=parent only, 3=no parent, 4=no child |
| `count` | `number` | Number of issues (1–100, default 20) |
| `offset` | `number` | Pagination offset (default 0) |
| `sort` | `string` | Sort field (created, updated, status, priority, dueDate, ...) |
| `order` | `asc\|desc` | Sort order (default desc) |

**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:**
| Field | Type | Description |
|---|---|---|
| `issueIdOrKey` | `string` | Issue key (e.g. `BLG-123`) or numeric issue ID |

**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:**
| Field | Type | Description |
|---|---|---|
| `issueIdOrKey` | `string` | Issue key (e.g. `BLG-123`) or numeric issue ID |
| `count` | `number` | Number of comments (1–100, default 20) |
| `order` | `asc\|desc` | `asc` = oldest first, `desc` = newest first (default) |
| `minId` | `number` | Return comments with ID >= minId |
| `maxId` | `number` | Return comments with ID <= maxId |

**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:**
| Field | Type | Description |
|---|---|---|
| `archived` | `boolean` | Omit = all, `false` = active only, `true` = archived only |

**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:**
| Field | Type | Description |
|---|---|---|
| `projectIdOrKey` | `string` | **Required.** Project key (e.g. `MYPROJ`) or numeric ID |
| `keyword` | `string` | Filter by display name or userId (case-insensitive) |

**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:**
| Field | Type | Description |
|---|---|---|
| `projectIdOrKey` | `string` | Project key (e.g. `MYPROJ`) or numeric project ID |

**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:**
| Field | Type | Description |
|---|---|---|
| `projectIdOrKey` | `string` | Project key (e.g. `MYPROJ`) or numeric project ID |

**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:**
| Field | Type | Description |
|---|---|---|
| `projectIdOrKey` | `string` | Project key (e.g. `MYPROJ`) or numeric project ID |
| `archived` | `boolean` | Include archived milestones (default: `false`) |

**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

```bash
# 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

| Code | Meaning |
|---|---|
| `API_KEY_MISSING` | `BACKLOG_API_KEY` is not set in environment |
| `BACKLOG_HTTP_ERROR` | Unexpected HTTP error from Backlog REST API (e.g. 401, 403, 404) |
| `BACKLOG_RESPONSE_ERROR` | Backlog returned an unexpected response shape |
| `CONFIG_ERROR` | Invalid or missing environment variable |
| `INVALID_INPUT` | Tool input failed validation |

## 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.