Backlog

You can run and consume the Backlog MCP Server to access Backlog API features programmatically. This server lets you manage projects, issues, users, and files, and to search and comment on items, all from MCP client integrations.

How to use

You connect your MCP client to the Backlog MCP Server to perform project management, issue handling, user lookups, file operations, and search. Use the available endpoints to fetch spaces and projects, create and update issues, add comments, and run searches across projects.

How to install

Prerequisites: install a modern Node.js environment on your system.

Step 1: Install dependencies and build the MCP server.

# Install dependencies
npm install

# Build the MCP server
npm run build

Step 2: Run the MCP server locally.

npm start

Step 3: (Optional) Test the server setup using the provided test commands.

npm test
npm run test:watch
npm run test:coverage

Configuration and runtime options

Environment variables are used to configure the server and connect to Backlog APIs.

Required environment variables shown in examples:

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

# Optional test settings
TEST_PROJECT_ID=your-test-project-id
TEST_PROJECT_KEY=your-test-project-key

Using Claude Desktop with MCP

If you use Claude Desktop, you can configure a dedicated MCP server entry that runs the MCP server via npx with the required environment variables.

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

Notes on local and desktop runs

When running locally, reproduce the final start command from the build/run steps. In this setup, you build with npm run build and start with npm start.

Security and best practices

Keep your API key secure. Do not expose BACKLOG_API_KEY in client-side code or public repositories. Use environment variables or secret management where possible.

Troubleshooting tips

If the server does not start, ensure dependencies are installed, a successful build completes, and the environment variables are correctly set. Check the logs for any authentication or connection errors to Backlog services.

Available tools

getSpaces

Fetches information about available spaces.

getProjects

Retrieves a list of projects.

getIssues

Gets a list of issues for a given project with optional pagination and sorting.

getIssue

Fetches detailed information for a single issue by ID or key.

createIssue

Creates a new issue with mandatory project, summary, and issue type, plus optional fields like priority, description, dates, and assignee.

updateIssue

Updates an existing issue with fields such as summary, description, status, priority, dates, and assignee.

addComment

Adds a comment to a specified issue.

searchIssues

Searches for issues across projects with keyword and optional filters.