Backlog MCP 服务器

MIT 许可证最后提交

📘 日本语でのご利用ガイド

用于与 Backlog API 交互的模型上下文协议 (MCP) 服务器。该服务器提供通过 Claude Desktop / Cline / Cursor 等 AI 代理管理 Backlog 中的项目、问题、wiki 页面等的工具。

特征

项目管理（创建、读取、更新、删除）
问题跟踪（创建、更新、删除、列出）
Wiki 页面管理
Git 仓库管理
拉取请求管理（创建、更新、列出、评论）
通知管理
关注列表管理
GraphQL 样式的字段选择，用于优化响应
大型响应的令牌限制
增强错误处理
以及更多 Backlog API 集成

Related MCP server: ConnectWise Manage MCP Server

要求

Docker
具有 API 访问权限的 Backlog 帐户
来自您的 Backlog 帐户的 API 密钥

安装

选项 1：通过 Docker 安装

使用此 MCP 服务器的最简单方法是通过 Claude Desktop 或 Cline 的 MCP 配置：

打开 Claude Desktop 或 Cline 设置
导航至 MCP 配置部分
添加以下配置：

{ "mcpServers": { "backlog": { "command": "docker", "args": [ "run", "-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" } } } }

将your-domain.backlog.com替换为您的 Backlog 域名，将your-api-key替换为您的 Backlog API 密钥。

高级配置选项

这是一种实验性的方法，并非减小上下文窗口大小的标准方法。如果您在将此 MCP 与任何 AI 代理配合使用时遇到问题，请尝试调整以下设置。您可以添加其他选项来自定义服务器行为：

{ "mcpServers": { "backlog": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "BACKLOG_DOMAIN", "-e", "BACKLOG_API_KEY", "-e", "MAX_TOKENS", "-e", "OPTIMIZE_RESPONSE", "ghcr.io/nulab/backlog-mcp-server" ], "env": { "BACKLOG_DOMAIN": "your-domain.backlog.com", "BACKLOG_API_KEY": "your-api-key", "MAX_TOKENS": "10000", "OPTIMIZE_RESPONSE": "true" } } } }

MAX_TOKENS ：响应中允许的最大令牌数（默认值：50000）
OPTIMIZE_RESPONSE ：启用 GraphQL 样式的字段选择以优化响应大小（默认值：false）

保持 Docker 镜像为最新

默认情况下，如果之前已拉取过镜像，Docker 将使用本地缓存的镜像。为了确保始终使用最新版本的ghcr.io/nulab/backlog-mcp-server ，请考虑以下方法之一：

选项 1： `--pull always` （推荐）

如果您使用的是 Docker 20.10 或更高版本，则可以修改args数组以包含--pull always标志：

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

这可确保 Docker 在运行之前始终从 GitHub Container Registry 中提取最新的镜像。

选项 2：手动拉取最新镜像

如果你的 Docker 版本不支持 --pull always，你可以在运行服务器之前手动拉取最新的镜像：

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

选项 2：手动安装

克隆存储库：
git clone https://github.com/nulab/backlog-mcp-server.git cd backlog-mcp-server
安装依赖项：
npm install
构建项目：
npm run build
设置你的 json 以用作 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" } } } }

可用工具

服务器提供了以下与 Backlog 交互的工具：

太空工具

工具名称	描述
`get_space`	返回有关 Backlog 空间的信息
`get_users`	返回 Backlog 空间中的用户列表
`get_myself`	返回有关已验证用户的信息
`get_priorities`	返回优先级列表
`get_resolutions`	返回问题解决方案列表
`get_issue_types`	返回项目的问题类型列表

项目工具

工具名称	描述
`get_project_list`	返回项目列表
`add_project`	创建新项目
`get_project`	返回有关特定项目的信息
`update_project`	更新现有项目
`delete_project`	删除项目
`get_custom_fields`	返回项目的自定义字段列表

发行工具

工具名称	描述
`get_issue`	返回有关特定问题的信息
`get_issues`	返回问题列表
`count_issues`	返回问题数量
`add_issue`	在指定项目中创建新问题
`update_issue`	更新现有问题
`delete_issue`	删除问题

评论工具

工具名称	描述
`get_issue_comments`	返回问题的评论列表
`add_issue_comment`	向问题添加评论

维基工具

工具名称	描述
`get_wiki_pages`	返回 Wiki 页面列表
`get_wikis_count`	返回项目中 wiki 页面的数量
`get_wiki`	返回有关特定 wiki 页面的信息
`add_wiki`	创建一个新的 wiki 页面

类别工具

工具名称	描述
`get_categories`	返回项目的类别列表

通知工具

工具名称	描述
`get_notifications`	返回通知列表
`count_notifications`	返回通知数量
`reset_unread_notification_count`	重置未读通知数量
`mark_notification_as_read`	将通知标记为已读

Git 存储库工具

工具名称	描述
`get_git_repositories`	返回项目的 Git 存储库列表
`get_git_repository`	返回有关特定 Git 存储库的信息

拉取请求工具

工具名称	描述
`get_pull_requests`	返回存储库的拉取请求列表
`get_pull_requests_count`	返回存储库的拉取请求数量
`get_pull_request`	返回有关特定拉取请求的信息
`add_pull_request`	创建一个新的拉取请求
`update_pull_request`	更新现有的拉取请求
`get_pull_request_comments`	返回拉取请求的评论列表
`add_pull_request_comment`	向拉取请求添加评论
`update_pull_request_comment`	更新拉取请求的评论

观看工具

工具名称	描述
`get_watching_list_items`	返回用户关注的项目列表
`get_watching_list_count`	返回用户观看的项目数量

使用示例

在 AI 代理中配置 MCP 服务器后，您就可以直接在对话中使用这些工具。以下是一些示例：

列出项目

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

使用 Git 存储库

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

使用字段选择

当启用OPTIMIZE_RESPONSE选项时，您可以使用 GraphQL 样式语法指定要检索的字段：

Show me the details of the PROJECT-KEY project, but only include the name, key, and description fields

AI将使用字段选择来优化响应：

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

这减少了响应大小和处理时间，特别是对于大型对象。

高级功能

响应优化

字段选择

启用OPTIMIZE_RESPONSE=true后，您可以使用 GraphQL 样式的语法来选择特定字段：

{ id name description users { id name } }

这允许您：

通过仅请求所需字段来减少响应大小
关注特定数据点
提高大型响应的性能

代币限制

大型响应会自动受到限制，以防止超出令牌限制：

默认限制：50,000 个令牌
可通过MAX_TOKENS环境变量进行配置
超出限制的响应将被截断并显示一条消息

i18n / 覆盖描述

您可以通过在主目录中创建.backlog-mcp-serverrc.json文件来覆盖工具的描述。

该文件应包含一个 JSON 对象，其中工具名称作为键，新描述作为值。
例如：

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

服务器启动时，根据以下优先级确定每个工具的最终描述：

环境变量（例如， BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION ）
.backlog-mcp-serverrc.json中的条目 - 支持的配置文件格式：.json、.yaml、.yml
内置后备值（英语）

示例配置：

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

导出当前翻译

您可以通过使用 --export-translations 标志运行二进制文件来导出当前默认翻译（包括任何覆盖）。

这会将所有工具描述打印到标准输出，包括您所做的任何自定义。

例子：

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

或者

npx github:nulab/backlog-mcp-server --export-translations

使用日语翻译模板

以下位置提供了日语配置文件示例：

translationConfig/.backlog-mcp-serverrc.json.example

要使用它，请将其作为 .backlog-mcp-serverrc.json 复制到您的主目录：

然后您可以编辑该文件以根据需要自定义描述。

使用环境变量

或者，您可以通过环境变量覆盖工具描述。

环境变量名称基于工具键，以 BACKLOG_MCP_ 为前缀并以大写形式书写。

示例：要覆盖 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" } } } }

服务器启动时同步加载配置文件。

环境变量始终优先于配置文件。

发展

运行测试

npm test

添加新工具

按照现有工具的模式在src/tools/中创建一个新文件
创建相应的测试文件
将新工具添加到src/tools/tools.ts
构建并测试您的更改

命令行选项

该服务器支持多个命令行选项：

--export-translations ：导出所有翻译键和值
--optimize-response ：启用 GraphQL 样式的字段选择
--max-tokens=NUMBER ：设置响应的最大令牌限制

例子：

node build/index.js --optimize-response --max-tokens=100000

执照

该项目已获得MIT 许可。

请注意：此工具根据 MIT 许可证提供**，不提供任何担保或官方支持**。
在查看内容并确定其是否适合您的需要后，请自行承担使用风险。
如果您遇到任何问题，请通过GitHub Issues报告。