by nulab
Provides a set of AI‑friendly tools for creating, reading, updating and deleting Backlog resources such as projects, issues, wiki pages, Git repositories and notifications, with optional response optimization and token limiting.
Backlog MCP Server exposes Backlog’s REST API as a collection of structured tools that AI agents can invoke. It covers the full lifecycle of Backlog entities – spaces, projects, issues, versions, wiki pages, Git repositories, pull requests, notifications, and documents – while offering features like GraphQL‑style field selection, token limits, and dynamic toolset discovery.
npx:
{
"mcpServers": {
"backlog": {
"command": "npx",
"args": ["backlog-mcp-server"],
"env": {
"BACKLOG_DOMAIN": "your-domain.backlog.com",
"BACKLOG_API_KEY": "your-api-key"
}
}
}
}
Replace the placeholders with your Backlog domain and API key.ENABLE_TOOLSETS, MAX_TOKENS, PREFIX, --optimize-response.get_project, add_issue, add_pull_request, etc.--enable-toolsets or ENABLE_TOOLSETS.MAX_TOKENS).npx, or manual Node.js setup.Q: Do I need to run Docker if I use npx?
A: No. npx runs the pre‑built binary directly from the npm registry, which is sufficient for most environments.
Q: How can I limit the size of responses?
A: Set the MAX_TOKENS environment variable (e.g., MAX_TOKENS=10000). The server will truncate large payloads and add a warning.
Q: Can I disable specific tools I don’t need?
A: Yes. Use --enable-toolsets or the ENABLE_TOOLSETS env var to list only the required toolsets.
Q: What if I need tool names to avoid conflicts with other MCP servers?
A: Provide a prefix with --prefix or the PREFIX env variable (e.g., PREFIX=backlog_).
Q: Is there support for Japanese language descriptions?
A: A sample Japanese translation file is included. Place it as ~/.backlog-mcp-serverrc.json or override via environment variables.
Q: How do I export the current set of tool descriptions?
A: Run the server with --export-translations to print all keys and values to stdout.
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.
The easiest way to use this MCP server is through MCP configurations:
{
"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
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.
{
"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.
Clone and install:
git clone https://github.com/nulab/backlog-mcp-server.git
cd backlog-mcp-server
npm install
npm run build
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"
}
}
}
}
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.
The following toolsets are available (enabled by default when "all" is used):
| Toolset | Description |
|---|---|
space |
Tools for managing Backlog space settings and general information |
project |
Tools for managing projects, categories, custom fields, and issue types |
issue |
Tools for managing issues and their comments, version milestones |
wiki |
Tools for managing wiki pages |
git |
Tools for managing Git repositories and pull requests |
notifications |
Tools for managing user notifications |
document |
Tools for viewing documents and document trees |
You can control toolset activation in the following ways:
Using via CLI:
--enable-toolsets space,project,issue
Or via environment variable:
ENABLE_TOOLSETS="space,project,issue"
If all is specified, all available toolsets will be enabled. This is also the default behavior.
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.
🧩 Tip:
projecttoolset is highly recommended, as many other tools rely on project data as an entry point.
If you're using the MCP server with AI agents, you can enable dynamic discovery of toolsets at runtime:
Enabling via CLI:
--dynamic-toolsets
Or via environment variable::
-e DYNAMIC_TOOLSETS=1 \
With dynamic toolsets enabled, the LLM will be able to list and activate toolsets on demand via tool interface.
spaceTools for managing Backlog space settings and general information.
get_space: Returns information about the Backlog space.get_users: Returns list of users in the Backlog space.get_myself: Returns information about the authenticated user.projectTools for managing projects, categories, custom fields, and issue types.
get_project_list: Returns list of projects.add_project: Creates a new project.get_project: Returns information about a specific project.update_project: Updates an existing project.delete_project: Deletes a project.issueTools for managing issues, their comments, and related items like priorities, categories, custom fields, issue types, resolutions, and watching lists.
get_issue: Returns information about a specific issue.get_issues: Returns list of issues.count_issues: Returns count of issues.add_issue: Creates a new issue in the specified project.update_issue: Updates an existing issue.delete_issue: Deletes an issue.get_issue_comments: Returns list of comments for an issue.add_issue_comment: Adds a comment to an issue.get_priorities: Returns list of priorities.get_categories: Returns list of categories for a project.get_custom_fields: Returns list of custom fields for a project.get_issue_types: Returns list of issue types for a project.get_resolutions: Returns list of issue resolutions.get_watching_list_items: Returns list of watching items for a user.get_watching_list_count: Returns count of watching items for a user.add_watching: Adds a new watch to an issue.update_watching: Updates an existing watch note.delete_watching: Deletes a watch from an issue.mark_watching_as_read: Marks a watch as read.get_version_milestone_list: Returns list of version milestones for a project.add_version_milestone: Creates a new version milestone for a project.update_version_milestone: Updates an existing version milestone.delete_version_milestone: Deletes a version milestone.wikiTools for managing wiki pages.
get_wiki_pages: Returns list of Wiki pages.get_wikis_count: Returns count of wiki pages in a project.get_wiki: Returns information about a specific wiki page.add_wiki: Creates a new wiki page.gitTools for managing Git repositories and pull requests.
get_git_repositories: Returns list of Git repositories for a project.get_git_repository: Returns information about a specific Git repository.get_pull_requests: Returns list of pull requests for a repository.get_pull_requests_count: Returns count of pull requests for a repository.get_pull_request: Returns information about a specific pull request.add_pull_request: Creates a new pull request.update_pull_request: Updates an existing pull request.get_pull_request_comments: Returns list of comments for a pull request.add_pull_request_comment: Adds a comment to a pull request.update_pull_request_comment: Updates a comment on a pull request.notificationsTools for managing user notifications.
get_notifications: Returns list of notifications.get_notifications_count: Returns count of notifications.reset_unread_notification_count: Resets unread notification count.mark_notification_as_read: Marks a notification as read.documentTools for managing documents and document trees in Backlog projects.
get_document_tree: Returns the hierarchical tree of documents for a project, including folders and neget_documents: Returns a flat list of documents in a project or folder.get_document: Returns detailed information about a specific document, including metadata, content, anOnce the MCP server is configured in AI agents, you can use the tools directly in your conversations. Here are some examples:
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 the details of the PROJECT-KEY project
List all Git repositories in the PROJECT-KEY project
Show me all open pull requests in the repository "repo-name" of PROJECT-KEY project
Create a new pull request from branch "feature/new-feature" to "main" in the repository "repo-name" of PROJECT-KEY project
Show me all items I'm watching
You can override the descriptions of tools by creating a .backlog-mcp-serverrc.json file in your home directory.
The file should contain a JSON object with the tool names as keys and the new descriptions as values.
For example:
{
"TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "An alternative description",
"TOOL_CREATE_PROJECT_DESCRIPTION": "Create a new project in Backlog"
}
When the server starts, it determines the final description for each tool based on the following priority:
BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION).backlog-mcp-serverrc.json - Supported configuration file formats: .json, .yaml, .ymlSample config:
{
"mcpServers": {
"backlog": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "BACKLOG_DOMAIN",
"-e", "BACKLOG_API_KEY",
"-v", "/yourcurrentdir/.backlog-mcp-serverrc.json:/root/.backlog-mcp-serverrc.json:ro",
"ghcr.io/nulab/backlog-mcp-server"
],
"env": {
"BACKLOG_DOMAIN": "your-domain.backlog.com",
"BACKLOG_API_KEY": "your-api-key"
}
}
}
}
You can export the current default translations (including any overrides) by running the binary with the --export-translations flag.
This will print all tool descriptions to stdout, including any customizations you have made.
Example:
docker run -i --rm ghcr.io/nulab/backlog-mcp-server node build/index.js --export-translations
or
npx github:nulab/backlog-mcp-server --export-translations
A sample Japanese configuration file is provided at:
translationConfig/.backlog-mcp-serverrc.json.example
To use it, copy it to your home directory as .backlog-mcp-serverrc.json:
You can then edit the file to customize the descriptions as needed.
Alternatively, you can override tool descriptions via environment variables.
The environment variable names are based on the tool keys, prefixed with BACKLOG_MCP_ and written in uppercase.
Example: To override the TOOL_ADD_ISSUE_COMMENT_DESCRIPTION:
{
"mcpServers": {
"backlog": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "BACKLOG_DOMAIN",
"-e", "BACKLOG_API_KEY",
"-e", "BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION"
"ghcr.io/nulab/backlog-mcp-server"
],
"env": {
"BACKLOG_DOMAIN": "your-domain.backlog.com",
"BACKLOG_API_KEY": "your-api-key",
"BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "An alternative description"
}
}
}
}
The server loads the config file synchronously at startup.
Environment variables always take precedence over the config file.
Add prefix to tool names with:
--prefix backlog_
or via environment variable:
PREFIX="backlog_"
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.
--optimize-response
Or environment variable:
OPTIMIZE_RESPONSE=1
Then, request only specific fields:
get_project(projectIdOrKey: "PROJECT-KEY", fields: "{ name key description }")
The AI will use field selection to optimize the response:
get_project(projectIdOrKey: "PROJECT-KEY", fields: "{ name key description }")
Benefits:
Large responses are automatically limited to prevent exceeding token limits:
MAX_TOKENS environment variableYou can change this using:
MAX_TOKENS=10000
If a response exceeds the limit, it will be truncated with a warning.
Note: This is a best-effort mitigation, not a guaranteed enforcement.
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.
{
"mcpServers": {
"backlog": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "BACKLOG_DOMAIN",
"-e", "BACKLOG_API_KEY",
"-e", "MAX_TOKENS",
"-e", "OPTIMIZE_RESPONSE",
"-e", "PREFIX",
"-e", "ENABLE_TOOLSETS",
"ghcr.io/nulab/backlog-mcp-server"
],
"env": {
"BACKLOG_DOMAIN": "your-domain.backlog.com",
"BACKLOG_API_KEY": "your-api-key",
"MAX_TOKENS": "10000",
"OPTIMIZE_RESPONSE": "1",
"PREFIX": "backlog_",
"ENABLE_TOOLSETS": "space,project,issue",
"ENABLE_DYNAMIC_TOOLSETS": "1"
}
}
}
}
npm test
src/tools/ following the pattern of existing toolssrc/tools/tools.tsThe server supports several command line options:
--export-translations: Export all translation keys and values--optimize-response: Enable GraphQL-style field selection--max-tokens=NUMBER: Set maximum token limit for responses--prefix=STRING: Optional string prefix to prepend to all tool names (default: "")--enable-toolsets <toolsets...>: Specify which toolsets to enable (comma-separated or multiple arguments). Defaults to "all".
Example: --enable-toolsets space,project or --enable-toolsets issue --enable-toolsets git
Available toolsets: space, project, issue, wiki, git, notifications.Example:
node build/index.js --optimize-response --max-tokens=100000 --prefix="backlog_" --enable-toolsets space,issue
This project is licensed under the MIT License.
Please note: This tool is provided under the MIT License without any warranty or official support.
Use it at your own risk after reviewing the contents and determining its suitability for your needs.
If you encounter any issues, please report them via GitHub Issues.
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by modelcontextprotocol
A Model Context Protocol server for Git repository interaction and automation.
by zed-industries
A high‑performance, multiplayer code editor designed for speed and collaboration.
by modelcontextprotocol
Model Context Protocol Servers
by modelcontextprotocol
A Model Context Protocol server that provides time and timezone conversion capabilities.
by cline
An autonomous coding assistant that can create and edit files, execute terminal commands, and interact with a browser directly from your IDE, operating step‑by‑step with explicit user permission.
by upstash
Provides up-to-date, version‑specific library documentation and code examples directly inside LLM prompts, eliminating outdated information and hallucinated APIs.
by daytonaio
Provides a secure, elastic infrastructure that creates isolated sandboxes for running AI‑generated code with sub‑90 ms startup, unlimited persistence, and OCI/Docker compatibility.
by continuedev
Enables faster shipping of code by integrating continuous AI agents across IDEs, terminals, and CI pipelines, offering chat, edit, autocomplete, and customizable agent workflows.
by github
Connects AI tools directly to GitHub, enabling natural‑language interactions for repository browsing, issue and pull‑request management, CI/CD monitoring, code‑security analysis, and team collaboration.
{
"mcpServers": {
"backlog": {
"command": "npx",
"args": [
"backlog-mcp-server"
],
"env": {
"BACKLOG_DOMAIN": "<YOUR_DOMAIN>",
"BACKLOG_API_KEY": "<YOUR_API_KEY>"
}
}
}
}claude mcp add backlog npx backlog-mcp-server