backlog

This MCP server exposes a set of Backlog tools (projects, issues, wiki pages, Git repos, notifications, and more) that AI agents can call through the MCP interface. It supports selective toolsets to reduce context size and can be run via Docker, npx, or a local Node.js setup. The included tools enable common Backlog operations like creating and updating projects, managing issues and comments, handling milestones, and interacting with wiki pages and Git data. Toolsets can be enabled or disabled to suit your AI agent's needs, and dynamic toolset discovery can be enabled for runtime activation of capabilities. To use, configure the backlog MCP in your MCP settings (e.g., the provided docker-based config), ensuring your Backlog domain and API key are supplied as environment variables. When started, the server will listen for MCP requests and respond with structured data optimized by the GraphQL-like field selection feature.

Prerequisites:

• Docker installed (or Node.js if you choose the Node.js/manual path)
• A Backlog account with API access
• Backlog API key

Option A: Install via Docker (recommended)

1. Ensure Docker is running
2. Use the MCP configuration provided in this README (or add a similar entry to your MCP config)
3. Start the MCP server through your MCP orchestration; docker will pull the image and run it with your environment variables

Option B: Install via npx (quick start)

1. Ensure Node.js and npm are installed
2. In your MCP settings, add a backlog server entry with: { "mcpServers": { "backlog": { "command": "npx", "args": ["backlog-mcp-server"], "env": { "BACKLOG_DOMAIN": "your-domain.backlog.com", "BACKLOG_API_KEY": "your-api-key" } } } }
3. Save and run; the MCP system will execute the backlog-mcp-server via npx when needed

Option C: Manual Setup (Node.js)

1. Clone the repository and install dependencies: git clone https://github.com/nulab/backlog-mcp-server.git cd backlog-mcp-server npm install npm run build
2. Create a .env file (or use .env.template) and set: BACKLOG_DOMAIN=your-domain.backlog.com BACKLOG_API_KEY=your-api-key
3. Run locally: npm run dev
4. In your MCP config, reference the built index.js: { "mcpServers": { "backlog": { "command": "node", "args": ["path/to/build/index.js"], "env": { "BACKLOG_DOMAIN": "your-domain.backlog.com", "BACKLOG_API_KEY": "your-api-key" } } } }

Tips and common issues:

• Ensure BACKLOG_DOMAIN and BACKLOG_API_KEY are kept secret and not checked into version control.
• If using Docker, consider enabling --pull always to guarantee the latest image is used, or manually pull updates with docker pull ghcr.io/nulab/backlog-mcp-server:latest.
• Toolsets can be toggled with --enable-toolsets (e.g., space,project,issue) or via ENABLE_TOOLSETS environment variable. Use project-heavy configurations to improve reliability.
• If you encounter authentication failures, verify the API key scope and domain configuration in Backlog.
• GraphQL-style field selection helps limit response payloads; specify only needed fields in queries when using the MCP tools.