Skip to content
Back to search

backlog-mcp-server

A Model Context Protocol (MCP) server for interacting with the Backlog API. This server provides tools for managing projects, issues, wiki pages, and more in Backlog through AI agents like Claude…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/nulab/backlog-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/nulab/backlog-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nulab--backlog-mcp-server/badge.svg)](/listings/nulab--backlog-mcp-server)

HTML

<a href="/listings/nulab--backlog-mcp-server"><img src="/api/listings/nulab--backlog-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requirements

- Docker - A Backlog account with API access - API key from your Backlog account

Option 1: Install via Docker

The easiest way to use this MCP server is through MCP configurations:

1. Open MCP settings 2. Navigate to the MCP configuration section 3. Add the following configuration:

{
  "mcpServers": {
    "backlog": {
      "command": "docker",
      "args": [
        "run",
        "--pull",
        "always",
        "-i",
        "--rm",
        "-e",
        "BACKLOG_DOMAIN",
        "-e",
        "BACKLOG_API_KEY",
        "ghcr.io/nulab/backlog-mcp-server"
      ],
      "env": {
        "BACKLOG_DOMAIN": "your-domain.backlog.com",
        "BACKLOG_API_KEY": "your-api-key"
      }
    }
  }
}

Replace `your-domain.backlog.com` with your Backlog domain and `your-api-key` with your Backlog API key.

✅ If you cannot use --pull always, you can manually update the image using:

docker pull ghcr.io/nulab/backlog-mcp-server:latest

Option 2: Install via npx

You can also run the server directly using `npx` without cloning the repository. This is a convenient way to run the server without a full installation.

1. Open MCP settings 2. Navigate to the MCP configuration section 3. Add the following configuration:

{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": ["backlog-mcp-server"],
      "env": {
        "BACKLOG_DOMAIN": "your-domain.backlog.com",
        "BACKLOG_API_KEY": "your-api-key"
      }
    }
  }
}

Replace `your-domain.backlog.com` with your Backlog domain and `your-api-key` with your Backlog API key.

Option 3: Manual Setup (Node.js)

1. Clone and install:

   git clone https://github.com/nulab/backlog-mcp-server.git
   cd backlog-mcp-server
   pnpm install
   pnpm run build

2. Create `.env` from template and set required variables:

cp .env.example .env

Set the following values in `.env`:

- `BACKLOG_DOMAIN=your-domain.backlog.com` - `BACKLOG_API_KEY=your-api-key`

3. Run locally:

pnpm run dev

4. Set your json to use as MCP

{
  "mcpServers": {
    "backlog": {
      "command": "node",
      "args": ["your-repository-location/build/index.js"],
      "env": {
        "BACKLOG_DOMAIN": "your-domain.backlog.com",
        "BACKLOG_API_KEY": "your-api-key"
      }
    }
  }
}

HTTP transport (Streamable HTTP)

By default the server uses **stdio**. To run the [MCP Streamable HTTP](https://modelcontextprotocol.io/) transport instead (JSON-RPC over HTTP, same tools as stdio), start with `--transport http` or set `MCP_TRANSPORT=http`.

pnpm run build
MCP_TRANSPORT=http MCP_HTTP_PORT=3333 node build/index.js

- **Endpoint:** `POST` (and `GET` for server-initiated streams) on `http://<host>:<port><path>` (default path `/mcp`). - **Protocol:** MCP `2026-07-28`. The protocol is stateless: there is no `initialize` handshake and no `mcp-session-id` header. Clients send their metadata in `_meta` on every request and discover capabilities via `server/discover`. Streamable HTTP also requires the `Mcp-Method` header (and `Mcp-Name` on `tools/call`). - **Backward compatibility:** Clients on `2025-11-25` and earlier are still served over the same endpoint, statelessly. Because no session is kept, the 2025 session operations (`GET` / `DELETE` with an `mcp-session-id`) answer `405`. - **Security:** Default bind is `127.0.0.1`. On a bare loopback bind, `Host` and `Origin` are both validated against the localhost set (DNS rebinding protection). Behind a reverse proxy, set `--http-allowed-hosts` to the public hostname; that turns off the localhost `Origin` default, since a browser client's `Origin` is its own site and never this server's hostname. Add `--http-allowed-origins` to restrict which client origins may reach the server. Do not expose the HTTP port to untrusted networks without authentication and TLS; it allows full use of your Backlog API key via MCP tools.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 792 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Backlog MCP Server
  2. [![MCP Toplist](https://mcptoplist.com/badge/glama%2Fnulab%2Fbacklog-mcp-server.svg)](https://mcptoplist.com/server/glama%2Fnulab%2Fbacklog-mcp-server)
  3. ![MIT License](https://img.shields.io/badge/license-MIT-green.svg)
  4. ![Build](https://github.com/nulab/backlog-mcp-server/actions/workflows/ci.yml/badge.svg)
  5. ![Last Commit](https://img.shields.io/github/last-commit/nulab/backlog-mcp-server.svg)
  6. [📘 日本語でのご利用ガイド](./README.ja.md)
  7. A Model Context Protocol (MCP) server for interacting with the Backlog API. This server provides tools for managing projects, issues, wiki pages, and more in Backlog through AI agents like Claude Desktop / Cline / Cursor etc.
  8. ## Features
  9. - Project tools (create, read, update, delete)
  10. - Issue tracking and comments (create, update, delete, list)
  11. - Version/Milestone management (create, read, update, delete)
  12. - Wiki page support
  13. - Git repository and pull request tools
  14. - Notification tools
  15. - Field selection for optimized responses
  16. - Token limiting for large responses
  17. ## Getting Started
  18. ### Requirements
  19. - Docker
  20. - A Backlog account with API access
  21. - API key from your Backlog account
  22. ### Option 1: Install via Docker
  23. The easiest way to use this MCP server is through MCP configurations:
  24. 1. Open MCP settings
  25. 2. Navigate to the MCP configuration section
  26. 3. Add the following configuration:
  27. ```json
  28. {
  29. "mcpServers": {
  30. "backlog": {
  31. "command": "docker",
  32. "args": [
  33. "run",
  34. "--pull",
  35. "always",
  36. "-i",
  37. "--rm",
  38. "-e",
  39. "BACKLOG_DOMAIN",
  40. "-e",
  41. "BACKLOG_API_KEY",
  42. "ghcr.io/nulab/backlog-mcp-server"
  43. ],
  44. "env": {
  45. "BACKLOG_DOMAIN": "your-domain.backlog.com",
  46. "BACKLOG_API_KEY": "your-api-key"
  47. }
  48. }
  49. }
  50. }
  51. ```
  52. Replace `your-domain.backlog.com` with your Backlog domain and `your-api-key` with your Backlog API key.
  53. ✅ If you cannot use --pull always, you can manually update the image using:
  54. ```
  55. docker pull ghcr.io/nulab/backlog-mcp-server:latest
  56. ```
  57. ### Option 2: Install via npx
  58. You can also run the server directly using `npx` without cloning the repository. This is a convenient way to run the server without a full installation.
  59. 1. Open MCP settings
  60. 2. Navigate to the MCP configuration section
  61. 3. Add the following configuration:
  62. ```json
  63. {
  64. "mcpServers": {
  65. "backlog": {
  66. "command": "npx",
  67. "args": ["backlog-mcp-server"],
  68. "env": {
  69. "BACKLOG_DOMAIN": "your-domain.backlog.com",
  70. "BACKLOG_API_KEY": "your-api-key"
  71. }
  72. }
  73. }
  74. }
  75. ```
  76. Replace `your-domain.backlog.com` with your Backlog domain and `your-api-key` with your Backlog API key.
  77. ### Option 3: Manual Setup (Node.js)
  78. 1. Clone and install:
  79. ```bash
  80. git clone https://github.com/nulab/backlog-mcp-server.git
  81. cd backlog-mcp-server
  82. pnpm install
  83. pnpm run build
  84. ```
  85. 2. Create `.env` from template and set required variables:
  86. ```bash
  87. cp .env.example .env
  88. ```
  89. Set the following values in `.env`:
  90. - `BACKLOG_DOMAIN=your-domain.backlog.com`
  91. - `BACKLOG_API_KEY=your-api-key`
  92. 3. Run locally:
  93. ```bash
  94. pnpm run dev
  95. ```
  96. 4. Set your json to use as MCP
  97. ```json
  98. {
  99. "mcpServers": {
  100. "backlog": {
  101. "command": "node",
  102. "args": ["your-repository-location/build/index.js"],
  103. "env": {
  104. "BACKLOG_DOMAIN": "your-domain.backlog.com",
  105. "BACKLOG_API_KEY": "your-api-key"
  106. }
  107. }
  108. }
  109. }
  110. ```
  111. ### HTTP transport (Streamable HTTP)
  112. By default the server uses **stdio**. To run the [MCP Streamable HTTP](https://modelcontextprotocol.io/) transport instead (JSON-RPC over HTTP, same tools as stdio), start with `--transport http` or set `MCP_TRANSPORT=http`.
  113. ```bash
  114. pnpm run build
  115. MCP_TRANSPORT=http MCP_HTTP_PORT=3333 node build/index.js
  116. ```
  117. - **Endpoint:** `POST` on `http://<host>:<port><path>` (default path `/mcp`). MCP `2026-07-28` has no standalone `GET` stream endpoint; change notifications use a `subscriptions/listen` POST whose response can remain an SSE stream. This server returns `405` for `GET` and `DELETE` on the MCP endpoint.
  118. - **Protocol:** MCP `2026-07-28`. The protocol is stateless: there is no `initialize` handshake and no `mcp-session-id` header. Clients send their metadata in `_meta` on every request and discover capabilities via `server/discover`. Streamable HTTP also requires the `Mcp-Method` header (and `Mcp-Name` on `tools/call`).
  119. - **Backward compatibility:** Clients on `2025-11-25` and earlier are still served over the same endpoint, statelessly. Because no session is kept, the 2025 session operations (`GET` / `DELETE` with an `mcp-session-id`) answer `405`.
  120. - **Security:** Default bind is `127.0.0.1`. On a bare loopback bind, `Host` and `Origin` are both validated against the localhost set (DNS rebinding protection). Behind a reverse proxy, set `--http-allowed-hosts` to the public hostname; that turns off the localhost `Origin` default, since a browser client's `Origin` is its own site and never this server's hostname. Add `--http-allowed-origins` to restrict which client origins may reach the server. Do not expose the HTTP port to untrusted networks without authentication and TLS; it allows full use of your Backlog API key via MCP tools.
  121. Environment variables (CLI flags override when both are set):
  122. | Variable | Description |
  123. | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  124. | `MCP_TRANSPORT` | `stdio` (default) or `http` |
  125. | `MCP_HTTP_HOST` | Bind address (default `127.0.0.1`) |
  126. | `MCP_HTTP_PORT` | Port (default `3333`) |
  127. | `MCP_HTTP_PATH` | URL path (default `/mcp`) |
  128. | `MCP_HTTP_JSON_RESPONSE` | `true` to prefer JSON responses over SSE (applies to `2026-07-28` clients only) |
  129. | `MCP_HTTP_ALLOWED_HOSTS` | Comma-separated allowed `Host` hostnames (port-agnostic). Required when binding to `0.0.0.0`; also the escape hatch for a loopback bind behind a proxy (DNS rebinding protection) |
  130. | `MCP_HTTP_ALLOWED_ORIGINS` | Comma-separated allowed `Origin` hostnames for browser-based clients. Defaults to the localhost set on a bare loopback bind, and to no `Origin` check otherwise |
  131. ### OAuth 2.0 Authentication (Remote MCP)
  132. When exposing the MCP server over a network, you can enable OAuth 2.0 authentication so that each user authenticates with their own Backlog account instead of sharing a single API key.
  133. The server implements the [MCP Third-Party Authorization Flow](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) by acting as both an OAuth authorization server (for MCP clients) and an OAuth client (for Backlog).
  134. #### Prerequisites
  135. 1. Register an OAuth application in your Backlog space:
  136. - Go to your Backlog space → Personal Settings → Register Application
  137. - Set the **Redirect URI** to `<MCP_SERVER_BASE_URL>/callback` (e.g., `https://mcp.example.com/callback`)
  138. - Note the **Client ID** and **Client Secret**
  139. 2. Set the following environment variables (in addition to `BACKLOG_DOMAIN`):
  140. | Variable | Description |
  141. | ----------------------------- | --------------------------------------------------------------- |
  142. | `BACKLOG_OAUTH_CLIENT_ID` | OAuth Client ID from your Backlog application |
  143. | `BACKLOG_OAUTH_CLIENT_SECRET` | OAuth Client Secret from your Backlog application |
  144. | `MCP_SERVER_BASE_URL` | Public URL of your MCP server (e.g., `https://mcp.example.com`) |
  145. > **Note:** `BACKLOG_API_KEY` is **not required** when OAuth is enabled — each user authenticates with their own Backlog account.
  146. #### Example
  147. ```bash
  148. BACKLOG_DOMAIN=your-space.backlog.com \
  149. BACKLOG_OAUTH_CLIENT_ID=your-client-id \
  150. BACKLOG_OAUTH_CLIENT_SECRET=your-client-secret \
  151. MCP_SERVER_BASE_URL=https://mcp.example.com \
  152. node build/index.js --transport http --http-host 0.0.0.0 --http-port 3333 \
  153. --http-allowed-hosts mcp.example.com
  154. ```
  155. `--http-allowed-hosts` is required in practice when binding to `0.0.0.0`: without it there is no DNS rebinding protection, and the server logs a warning at startup.
  156. The server automatically exposes the following OAuth endpoints when OAuth is enabled:
  157. | Endpoint | Description |
  158. | ----------------------------------------------- | ----------------------------------------------------------------------------------------------- |
  159. | `GET /.well-known/oauth-authorization-server` | OAuth Authorization Server Metadata ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)) |
  160. | `GET /.well-known/oauth-protected-resource/mcp` | OAuth Protected Resource Metadata ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)) |
  161. | `POST /register` | Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) |
  162. | `GET /authorize` | Authorization endpoint (redirects to Backlog OAuth) |
  163. | `GET /callback` | Backlog OAuth callback |
  164. | `POST /token` | Token endpoint (authorization code & refresh token) |
  165. MCP clients that support the MCP authorization specification will use these endpoints automatically.
  166. `POST /register` restricts which redirect URIs a client may register. A loopback
  167. URI (`http://localhost`, `http://127.0.0.1`, `http://[::1]`) is how an app running
  168. on the user's machine receives the authorization code, and is accepted from a
  169. client that declares `"application_type": "native"` — or, when the field is
  170. absent, from one whose redirect URIs are _all_ loopback. A client declaring
  171. `"application_type": "web"`, or mixing a remote `https:` URI with a loopback one
  172. without declaring itself, is rejected with `invalid_client_metadata`.
  173. > **Limitations:**
  174. >
  175. > - OAuth mode currently supports a single Backlog organization. It is not compatible with the multi-organization configuration.
  176. > - Client registrations and tokens are stored in memory and will be lost on server restart.
  177. ## Tool Configuration
  178. You can selectively enable or disable specific **toolsets** using the `--enable-toolsets` command-line flag or the `ENABLE_TOOLSETS` environment variable. This allows better control over which tools are available to the AI agent and helps reduce context size.
  179. ### Available Toolsets
  180. The following toolsets are available (enabled by default when `"all"` is used):
  181. | Toolset | Description |
  182. | --------------- | ----------------------------------------------------------------------- |
  183. | `space` | Tools for managing Backlog space settings and general information |
  184. | `project` | Tools for managing projects, categories, custom fields, and issue types |
  185. | `issue` | Tools for managing issues and their comments, version milestones |
  186. | `wiki` | Tools for managing wiki pages |
  187. | `git` | Tools for managing Git repositories and pull requests |
  188. | `notifications` | Tools for managing user notifications |
  189. | `document` | Tools for viewing documents and document trees |
  190. ### Specifying Toolsets
  191. You can control toolset activation in the following ways:
  192. Using via CLI:
  193. ```bash
  194. --enable-toolsets space,project,issue
  195. ```
  196. Or via environment variable:
  197. ```
  198. ENABLE_TOOLSETS="space,project,issue"
  199. ```
  200. If all is specified, all available toolsets will be enabled. This is also the default behavior.
  201. Using selective toolsets can be helpful if the toolset list is too large for your AI agent or if certain tools are causing performance issues. In such cases, disabling unused toolsets may improve stability.
  202. > 🧩 Tip: `project` toolset is highly recommended, as many other tools rely on project data as an entry point.
  203. ## Available Tools
  204. ### Toolset: `space`
  205. Tools for managing Backlog space settings and general information.
  206. - `get_space`: Returns information about the Backlog space.
  207. - `get_users`: Returns list of users in the Backlog space.
  208. - `get_myself`: Returns information about the authenticated user.
  209. ### Toolset: `project`
  210. Tools for managing projects, categories, custom fields, and issue types.
  211. - `get_project_list`: Returns list of projects.
  212. - `add_project`: Creates a new project.
  213. - `get_project`: Returns information about a specific project.
  214. - `get_project_users`: Returns list of users in a specific project.
  215. - `update_project`: Updates an existing project.
  216. ### Toolset: `issue`
  217. Tools for managing issues, their comments, and related items like priorities, categories, custom fields, issue types, resolutions, and watching lists.
  218. - `get_issue`: Returns information about a specific issue.
  219. - `get_issue_attachment`: Downloads one attachment of an issue. Returns it as image or embedded resource content, or as base64 with `format: "base64"`.
  220. - `get_issues`: Returns list of issues.
  221. - `count_issues`: Returns count of issues.
  222. - `add_issue`: Creates a new issue in the specified project.
  223. - `update_issue`: Updates an existing issue.
  224. - `delete_issue`: Deletes an issue.
  225. - `get_issue_comments`: Returns list of comments for an issue.
  226. - `add_issue_comment`: Adds a comment to an issue.
  227. - `update_issue_comment`: Updates a comment on an issue.
  228. - `get_related_issues`: Returns list of issues related to a specific issue.
  229. - `add_related_issue`: Relates an issue to another issue.
  230. - `remove_related_issue`: Removes the relation between an issue and a related issue.
  231. - `get_priorities`: Returns list of priorities.
  232. - `get_categories`: Returns list of categories for a project.
  233. - `add_category`: Creates a new category for a project.
  234. - `get_custom_fields`: Returns list of custom fields for a project.
  235. - `get_issue_types`: Returns list of issue types for a project.
  236. - `get_resolutions`: Returns list of issue resolutions.
  237. - `get_watching_list_items`: Returns list of watching items for a user.
  238. - `get_watching_list_count`: Returns count of watching items for a user.
  239. - `add_watching`: Adds a new watch to an issue.
  240. - `update_watching`: Updates an existing watch note.
  241. - `delete_watching`: Deletes a watch from an issue.
  242. - `mark_watching_as_read`: Marks a watch as read.
  243. - `get_version_milestone_list`: Returns list of version milestones for a project.
  244. - `add_version_milestone`: Creates a new version milestone for a project.
  245. - `update_version_milestone`: Updates an existing version milestone.
  246. - `delete_version_milestone`: Deletes a version milestone.
  247. ### Toolset: `wiki`
  248. Tools for managing wiki pages.
  249. - `get_wiki_pages`: Returns list of Wiki pages.
  250. - `get_wikis_count`: Returns count of wiki pages in a project.
  251. - `get_wiki`: Returns information about a specific wiki page.
  252. - `add_wiki`: Creates a new wiki page.
  253. ### Toolset: `git`
  254. Tools for managing Git repositories and pull requests.
  255. - `get_git_repositories`: Returns list of Git repositories for a project.
  256. - `get_git_repository`: Returns information about a specific Git repository.
  257. - `get_pull_requests`: Returns list of pull requests for a repository.
  258. - `get_pull_requests_count`: Returns count of pull requests for a repository.
  259. - `get_pull_request`: Returns information about a specific pull request.
  260. - `add_pull_request`: Creates a new pull request.
  261. - `update_pull_request`: Updates an existing pull request.
  262. - `get_pull_request_comments`: Returns list of comments for a pull request.
  263. - `add_pull_request_comment`: Adds a comment to a pull request.
  264. - `update_pull_request_comment`: Updates a comment on a pull request.
  265. ### Toolset: `notifications`
  266. Tools for managing user notifications.
  267. - `get_notifications`: Returns list of notifications.
  268. - `get_notifications_count`: Returns count of notifications.
  269. - `reset_unread_notification_count`: Resets unread notification count.
  270. - `mark_notification_as_read`: Marks a notification as read.
  271. ### Toolset: `document`
  272. Tools for managing documents and document trees in Backlog projects.
  273. - `get_document_tree`: Returns the hierarchical tree of documents for a project, including folders and ne
  274. - `get_documents`: Returns a flat list of documents in a project or folder.
  275. - `get_document_comments`: Returns the comments on a document, including their replies.
  276. - `get_document`: Returns detailed information about a specific document, including metadata, content, an
  277. ## Usage Examples
  278. Once the MCP server is configured in AI agents, you can use the tools directly in your conversations. Here are some examples:
  279. - Listing Projects
  280. ```
  281. Could you list all my Backlog projects?
  282. ```
  283. - Creating a New Issue
  284. ```
  285. Create a new bug issue in the PROJECT-KEY project with high priority titled "Fix login page error"
  286. ```
  287. - Getting Project Details
  288. ```
  289. Show me the details of the PROJECT-KEY project
  290. ```
  291. - Working with Git Repositories
  292. ```
  293. List all Git repositories in the PROJECT-KEY project
  294. ```
  295. - Managing Pull Requests
  296. ```
  297. Show me all open pull requests in the repository "repo-name" of PROJECT-KEY project
  298. ```
  299. ```
  300. Create a new pull request from branch "feature/new-feature" to "main" in the repository "repo-name" of PROJECT-KEY project
  301. ```
  302. - Watching Items
  303. ```
  304. Show me all items I'm watching
  305. ```
  306. ### Overriding Tool Descriptions
  307. You can override the descriptions of tools by creating a `.backlog-mcp-serverrc.json` file in your **home directory**.
  308. Almost all of these strings are the tool and parameter descriptions the model reads when it decides which tool to call and how to fill in its arguments, so overriding them is a way to steer tool selection — for example to disambiguate two similar tools, or to add a rule your team follows — rather than a way to change the language of the answers you get. The model answers in whatever language you ask in, regardless of the language these descriptions are written in.
  309. A small number of keys are validation error messages instead (for example `PROJECT_ID_OR_KEY_REQUIRED`). Those are returned in the tool result when a call is rejected, so they can reach you by way of the model's reply.
  310. The file should contain a JSON object with the tool names as keys and the new descriptions as values.
  311. For example:
  312. ```json
  313. {
  314. "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "An alternative description",
  315. "TOOL_CREATE_PROJECT_DESCRIPTION": "Create a new project in Backlog"
  316. }
  317. ```
  318. When the server starts, it determines the final description for each tool based on the following priority:
  319. 1. Environment variables (e.g., `BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION`)
  320. 2. Entries in `.backlog-mcp-serverrc.json` - Supported configuration file formats: .json, .yaml, .yml
  321. 3. Built-in defaults
  322. Empty or non-string values are ignored at every level, and the built-in default is used instead.
  323. Sample config:
  324. ```json
  325. {
  326. "mcpServers": {
  327. "backlog": {
  328. "command": "docker",
  329. "args": [
  330. "run",
  331. "-i",
  332. "--rm",
  333. "-e",
  334. "BACKLOG_DOMAIN",
  335. "-e",
  336. "BACKLOG_API_KEY",
  337. "-v",
  338. "/yourcurrentdir/.backlog-mcp-serverrc.json:/root/.backlog-mcp-serverrc.json:ro",
  339. "ghcr.io/nulab/backlog-mcp-server"
  340. ],
  341. "env": {
  342. "BACKLOG_DOMAIN": "your-domain.backlog.com",
  343. "BACKLOG_API_KEY": "your-api-key"
  344. }
  345. }
  346. }
  347. }
  348. ```
  349. ### Exporting Current Descriptions
  350. You can export the current descriptions (including any overrides) by running the binary with the `--export-descriptions` flag. This flag was previously called `--export-translations`; the old name still works but prints a deprecation notice and will be removed in a future release.
  351. This prints every key that is resolved while the tool list is built, with its current value, including any customizations you have made. That covers all tool and parameter descriptions, and it is the practical way to discover key names.
  352. It does not cover the validation error messages, because those keys are only resolved when a call is actually rejected. They are still overridable by the same rules; you just have to read them out of the source.
  353. Example:
  354. ```bash
  355. docker run -i --rm ghcr.io/nulab/backlog-mcp-server node build/index.js --export-descriptions
  356. ```
  357. or
  358. ```bash
  359. npx github:nulab/backlog-mcp-server --export-descriptions
  360. ```
  361. ### Using Environment Variables
  362. Alternatively, you can override tool descriptions via environment variables.
  363. The environment variable names are based on the tool keys, prefixed with BACKLOG*MCP* and written in uppercase.
  364. Example:
  365. To override the TOOL_ADD_ISSUE_COMMENT_DESCRIPTION:
  366. ```json
  367. {
  368. "mcpServers": {
  369. "backlog": {
  370. "command": "docker",
  371. "args": [
  372. "run",
  373. "-i",
  374. "--rm",
  375. "-e", "BACKLOG_DOMAIN",
  376. "-e", "BACKLOG_API_KEY",
  377. "-e", "BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION"
  378. "ghcr.io/nulab/backlog-mcp-server"
  379. ],
  380. "env": {
  381. "BACKLOG_DOMAIN": "your-domain.backlog.com",
  382. "BACKLOG_API_KEY": "your-api-key",
  383. "BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "An alternative description"
  384. }
  385. }
  386. }
  387. }
  388. ```
  389. The server loads the config file synchronously at startup.
  390. Environment variables always take precedence over the config file.
  391. ## Advanced Features
  392. ### Tool Name Prefixing
  393. Add prefix to tool names with:
  394. ```
  395. --prefix backlog_
  396. ```
  397. or via environment variable:
  398. ```
  399. PREFIX="backlog_"
  400. ```
  401. This is especially useful if you're using multiple MCP servers or tools in the same environment and want to avoid name collisions. For example, get_project can become backlog_get_project to distinguish it from similarly named tools provided by other services.
  402. ### Response Optimization & Token Limits
  403. #### Response Compaction
  404. Tool results are compacted before they are returned. This is always on, and applies to every tool except `get_issue_attachment`, which returns the file itself:
  405. - A user nested in a result (`createdUser`, `assignee`, `stars[].presenter`, a notification's `sender`, …) is reduced to `id`, `userId` and `name`. A user that *is* the result — `get_myself`, the items of `get_users` or `get_project_users` — is returned whole.
  406. - A nested project (each activity's and notification's `project`) is reduced to `id`, `projectKey` and `name`, and a nested issue (a pull request's or notification's `issue`) to `id`, `issueKey`, `summary` and `status`. A project or issue that is the result — `get_project`, `get_issue`, the items of `get_project_list` or `get_issues` — is returned whole, and so is the issue of each item of `get_watching_list_items`.
  407. - Nested entities (statuses, issue types, categories, milestones, custom field items, …) omit `color` and `displayOrder`, and nested milestones also omit `description`. Tools that list these themselves (`get_issue_types`, `get_categories`, `get_version_milestone_list`, …) return them whole.
  408. - Fields that are `null`, an empty string or an empty array are omitted. `0`, `false` and `{}` are kept. This also applies to a field named in `fields`: an empty one is left out rather than returned as empty.
  409. - JSON is returned without indentation.
  410. #### Field Selection
  411. ```
  412. --optimize-response
  413. ```
  414. Or environment variable:
  415. ```
  416. OPTIMIZE_RESPONSE=1
  417. ```
  418. Tools that return a **list** then take an optional `fields` parameter: a list of
  419. top-level field names from that tool's own result, published as an enum so a name
  420. the tool does not have is rejected rather than ignored. Tools that return a single
  421. record do not get it — the parameter costs schema on every session, and one record
  422. has almost nothing to trim.
  423. ```
  424. get_project(projectIdOrKey: "PROJECT-KEY", fields: ["name", "key", "description"])
  425. ```
  426. Omitting `fields` returns the whole result. Selection is one level deep: naming an
  427. object or array field returns it whole.
  428. Benefits:
  429. - Reduce response size by requesting only needed fields
  430. - Focus on specific data points
  431. - Improve performance for large responses
  432. #### Token Limiting
  433. Large responses are automatically limited to prevent exceeding token limits:
  434. - Default limit: 50,000 tokens
  435. - Configurable via `MAX_TOKENS` environment variable
  436. - Responses exceeding the limit are truncated with a message
  437. You can change this using:
  438. ```
  439. MAX_TOKENS=10000
  440. ```
  441. If a response exceeds the limit, it will be truncated with a warning.
  442. > Note: This is a best-effort mitigation, not a guaranteed enforcement.
  443. ### Logging
  444. The server logs to **stderr** (stdout carries the JSON-RPC stream on the stdio transport).
  445. | Variable | Description |
  446. | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  447. | `LOG_LEVEL` | `fatal`, `error`, `warn`, `info`, `debug`, `trace` or `silent`. Defaults to `error` when `NODE_ENV` is `production` — which is also the default when `NODE_ENV` is unset — and to `debug` otherwise. An unrecognised value is reported and the default is used. |
  448. `NODE_ENV` still selects the output *format*: any value other than `production` switches to human-readable `pino-pretty` output when that package is available. Use `LOG_LEVEL`, not `NODE_ENV`, to change how much is logged, so that a deployment keeps structured JSON:
  449. `pino-pretty` is a development dependency, so neither the published npm package nor the container image carries a copy. In those, logs are structured JSON whatever `NODE_ENV` says, and `LOG_LEVEL` is the only setting that changes the output.
  450. ```
  451. LOG_LEVEL=info node build/index.js --transport http
  452. ```
  453. ### Full Custom Configuration Example
  454. This section demonstrates advanced configuration using multiple environment variables. These are experimental features and may not be supported across all MCP clients. This is not part of the MCP standard specification and should be used with caution.
  455. ```json
  456. {
  457. "mcpServers": {
  458. "backlog": {
  459. "command": "docker",
  460. "args": [
  461. "run",
  462. "-i",
  463. "--rm",
  464. "-e",
  465. "BACKLOG_DOMAIN",
  466. "-e",
  467. "BACKLOG_API_KEY",
  468. "-e",
  469. "MAX_TOKENS",
  470. "-e",
  471. "OPTIMIZE_RESPONSE",
  472. "-e",
  473. "PREFIX",
  474. "-e",
  475. "ENABLE_TOOLSETS",
  476. "ghcr.io/nulab/backlog-mcp-server"
  477. ],
  478. "env": {
  479. "BACKLOG_DOMAIN": "your-domain.backlog.com",
  480. "BACKLOG_API_KEY": "your-api-key",
  481. "MAX_TOKENS": "10000",
  482. "OPTIMIZE_RESPONSE": "1",
  483. "PREFIX": "backlog_",
  484. "ENABLE_TOOLSETS": "space,project,issue"
  485. }
  486. }
  487. }
  488. }
  489. ```
  490. ## Development
  491. ### Running Tests
  492. ```bash
  493. pnpm test
  494. ```
  495. ### Adding New Tools
  496. 1. Create a new file in `src/tools/` following the pattern of existing tools
  497. 2. Create a corresponding test file
  498. 3. Add the new tool to `src/tools/tools.ts`
  499. 4. Build and test your changes
  500. ### Command Line Options
  501. The server supports several command line options:
  502. - `--transport stdio|http`: MCP transport (default: stdio). Use `http` for Streamable HTTP.
  503. - `--http-host`, `--http-port`, `--http-path`: HTTP bind address, port, and path (defaults: `127.0.0.1`, `3333`, `/mcp`).
  504. - `--http-json-response`: Prefer JSON responses over SSE. Applies to `2026-07-28` clients only; the backward-compatible `2025-11-25` path is served with the SDK's default response shaping.
  505. - `--http-allowed-hosts`: Comma-separated allowed `Host` hostnames (port-agnostic). Needed when binding to all interfaces, or on a loopback bind behind a reverse proxy.
  506. - `--http-allowed-origins`: Comma-separated allowed `Origin` hostnames for browser-based clients. Defaults to the localhost set on a bare loopback bind, and to no `Origin` check otherwise.
  507. - `--export-descriptions`: Export the description keys and values resolved when building the tool list. Was named `--export-translations`; that spelling still works as a deprecated alias and will be removed in a future release
  508. - `--optimize-response`: Add a `fields` parameter to each tool for selecting which result fields to return
  509. - `--max-tokens=NUMBER`: Set maximum token limit for responses
  510. - `--prefix=STRING`: Optional string prefix to prepend to all tool names (default: "")
  511. - `--enable-toolsets <toolsets...>`: Specify which toolsets to enable (comma-separated or multiple arguments). Defaults to "all".
  512. Example: `--enable-toolsets space,project` or `--enable-toolsets issue --enable-toolsets git`
  513. Available toolsets: `space`, `project`, `issue`, `wiki`, `git`, `notifications`.
  514. Example:
  515. ```bash
  516. node build/index.js --optimize-response --max-tokens=100000 --prefix="backlog_" --enable-toolsets space,issue
  517. ```
  518. HTTP example:
  519. ```bash
  520. node build/index.js --transport http --http-port 3333 --http-path /mcp
  521. ```
  522. ## Multi-Organization Support
  523. This server can be configured to access multiple Backlog organizations from a single MCP server instance.
  524. ### Configuration
  525. Configure one env pair per organization and set a default organization:
  526. ```bash
  527. BACKLOG_DEFAULT_ORG=COMPANY_A
  528. BACKLOG_ORG_COMPANY_A_DOMAIN=company-a.backlog.com
  529. BACKLOG_ORG_COMPANY_A_API_KEY=your-company-a-api-key
  530. BACKLOG_ORG_COMPANY_B_DOMAIN=company-b.backlog.com
  531. BACKLOG_ORG_COMPANY_B_API_KEY=your-company-b-api-key
  532. ```
  533. This works whether the variables come from a local `.env`, your shell environment, or an MCP client config `env` block.
  534. Example MCP config:
  535. ```json
  536. {
  537. "env": {
  538. "BACKLOG_DEFAULT_ORG": "COMPANY_A",
  539. "BACKLOG_ORG_COMPANY_A_DOMAIN": "company-a.backlog.com",
  540. "BACKLOG_ORG_COMPANY_A_API_KEY": "your-company-a-api-key",
  541. "BACKLOG_ORG_COMPANY_B_DOMAIN": "company-b.backlog.com",
  542. "BACKLOG_ORG_COMPANY_B_API_KEY": "your-company-b-api-key"
  543. }
  544. }
  545. ```
  546. If no multi-organization env vars are set, the server falls back to the existing single-organization configuration:
  547. ```bash
  548. BACKLOG_DOMAIN=your-domain.backlog.com
  549. BACKLOG_API_KEY=your-api-key
  550. ```
  551. ### Tool Usage
  552. When multi-organization env vars are configured, all normal tools accept an optional `organization` input field. When provided, the tool call is routed to that Backlog organization.
  553. In single-organization mode the field is not published, since there would be only one organization to route to. Omitting it keeps roughly 8 KB of tool schema out of every `tools/list` response.
  554. Examples:
  555. ```json
  556. {
  557. "organization": "COMPANY_B",
  558. "projectKey": "PROJECT"
  559. }
  560. ```
  561. If `organization` is omitted:
  562. - the organization named by `BACKLOG_DEFAULT_ORG` is used
  563. - if multi-organization env vars are present and `BACKLOG_DEFAULT_ORG` is missing, the server fails at startup
  564. ### Organization Discovery
  565. In multi-organization mode the server provides a `list_organizations` tool that returns the configured organization names, their domains, and which one is the default. It is not registered in single-organization mode.
  566. Example response:
  567. ```json
  568. [
  569. {
  570. "name": "COMPANY_A",
  571. "domain": "company-a.backlog.com",
  572. "isDefault": true
  573. },
  574. {
  575. "name": "COMPANY_B",
  576. "domain": "company-b.backlog.com",
  577. "isDefault": false
  578. }
  579. ]
  580. ```
  581. ### Notes
  582. - For multi-org mode, every organization must define both `BACKLOG_ORG_<NAME>_DOMAIN` and `BACKLOG_ORG_<NAME>_API_KEY`.
  583. - The `<NAME>` part is the organization name exposed through the `organization` tool input and `list_organizations`.
  584. ## License
  585. This project is licensed under the [MIT License](./LICENSE).
  586. Please note: This tool is provided under the MIT License **without any warranty or official support**.
  587. Use it at your own risk after reviewing the contents and determining its suitability for your needs.
  588. If you encounter any issues, please report them via [GitHub Issues](../../issues).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.