Backlog MCP server for AI agents

The Backlog MCP Server is a tool that allows AI agents like Claude Desktop to interact with Backlog API for managing projects, issues, wikis, and more. It provides a standardized way to access Backlog features through the Model Context Protocol (MCP).

Installation Options

Docker Installation (Recommended)

The easiest way to set up the Backlog MCP Server is using Docker:

Add the following configuration to your MCP settings:

{
  "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 personal Backlog API key.

If you can't use --pull always, manually update the image with:

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

Node.js Installation

Alternatively, you can set up the server manually:

Clone and install the repository:

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

Configure MCP to use your local installation:

{
  "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 features are available and reduce context size:

Available Toolsets

space: Space settings and general information
project: Project management, categories, custom fields, issue types
issue: Issue tracking and comments
wiki: Wiki page management
git: Git repositories and pull requests
notifications: User notification management
document: Document viewing and management

Enabling Specific Toolsets

Via command line:

--enable-toolsets space,project,issue

Or environment variable:

ENABLE_TOOLSETS="space,project,issue"

The default value is "all", which enables all toolsets.

Dynamic Toolset Discovery

For AI agents, you can enable runtime discovery of toolsets:

Via command line:

--dynamic-toolsets

Or environment variable:

DYNAMIC_TOOLSETS=1

Usage Examples

Once configured, you can use the Backlog MCP server through your AI agent with natural language:

Listing Projects

Could you list all my Backlog projects?

Creating Issues

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

Working with Git

List all Git repositories in the PROJECT-KEY project

Managing Pull Requests

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

Advanced Features

Tool Name Prefixing

You can add prefixes to tool names to avoid collisions with other tools:

--prefix backlog_

Or via environment variable:

PREFIX="backlog_"

Response Optimization

Enable GraphQL-style field selection:

--optimize-response

Or via environment variable:

OPTIMIZE_RESPONSE=1

Then request only specific fields:

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

Token Limiting

Large responses are automatically limited to prevent exceeding token limits:

MAX_TOKENS=10000

The default limit is 50,000 tokens.

Customizing Tool Descriptions

Create a .backlog-mcp-serverrc.json file in your home directory to customize descriptions:

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

For Docker, mount this file:

"-v", "/yourcurrentdir/.backlog-mcp-serverrc.json:/root/.backlog-mcp-serverrc.json:ro"

You can also use environment variables with the prefix BACKLOG_MCP_:

BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="An alternative description"

To export current translations:

docker run -i --rm ghcr.io/nulab/backlog-mcp-server node build/index.js --export-translations

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