Backlog MCP server for AI agents

The Backlog MCP Server is a flexible tool that enables AI agents to interact with Backlog API, allowing management of projects, issues, wikis, Git repositories, and more through natural language commands.

Installation Options

Docker Installation (Recommended)

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

To manually update the Docker image:

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

NPX Installation

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

Manual Node.js Setup

Clone and install:

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

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

Configuring Toolsets

You can enable specific toolsets to control which capabilities are available:

Available Toolsets

space: Space settings and general information
project: Project management tools
issue: Issue tracking and comments
wiki: Wiki page management
git: Git repository and pull request tools
notifications: User notification management
document: Document viewing tools

Specify Toolsets

Via command line:

--enable-toolsets space,project,issue

Or via environment variable:

ENABLE_TOOLSETS="space,project,issue"

Dynamic Toolset Discovery

Enable on-demand toolset activation:

--dynamic-toolsets

Or:

DYNAMIC_TOOLSETS=1

Available Tools

Space Management

Get space information
List users
Get authenticated user information

Project Management

List, create, view, update, and delete projects

Issue Management

Create, view, update, and delete issues
Manage issue comments
View and manage priorities, categories, custom fields
Handle version milestones

Wiki Management

List, count, view, and create wiki pages

Git Management

Manage repositories and pull requests
Create and update pull requests
Handle pull request comments

Notification Management

View and manage notifications
Mark notifications as read

Document Management

View document trees and individual documents

Usage Examples

Once configured, use natural language to interact with Backlog:

Could you list all my Backlog projects?

Create a new bug issue in the PROJECT-KEY project with high priority titled "Fix login page error"

Show me all open pull requests in the repository "repo-name" of PROJECT-KEY project

Advanced Features

Tool Name Prefixing

Add prefixes to avoid name collisions:

--prefix backlog_

Or:

PREFIX="backlog_"

Response Optimization

Enable GraphQL-style field selection:

--optimize-response

Or:

OPTIMIZE_RESPONSE=1

Then you can request specific fields:

get_project(projectIdOrKey: "PROJECT-KEY", fields: "{ name key description }")

Token Limiting

Limit large responses:

MAX_TOKENS=10000

Translation Customization

Override tool descriptions using .backlog-mcp-serverrc.json in your home directory:

{
  "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "An alternative description",
  "TOOL_CREATE_PROJECT_DESCRIPTION": "Create a new project in Backlog"
}

Or via environment variables:

BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="An alternative description"

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect