Backlog MCP 服务器

📘 日语使用指南

这是一个用于与Backlog API交互的Model Context Protocol (MCP) 服务器。该服务器提供了通过像Claude Desktop / Cline / Cursor等AI代理来管理Backlog中的项目、问题、维基页面等功能的工具。

功能

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

要求

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

安装

选项1：通过Docker安装

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

1. 打开Claude Desktop或Cline设置
2. 导航到MCP配置部分
3. 添加以下配置：

json
{
"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密钥。

高级配置选项

这是一种实验性方法，不是减少上下文窗口大小的标准方式。
如果您在使用任何AI代理时遇到困难，请尝试调整以下设置。
您可以添加额外选项来自定义服务器行为：

json
{
"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标志：

json
{
"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：手动安装

1. 克隆仓库：
   bash
   git clone https://github.com/nulab/backlog-mcp-server.git
   cd backlog-mcp-server

2. 安装依赖项：
   bash
   npm install

3. 构建项目：
   bash
   npm run build

4. 设置您的 JSON 以用作 MCP
   json
   {
   "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	向议题添加评论

Wiki 工具

工具名称	描述
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服务器，您就可以直接在对话中使用这些工具。以下是一些示例：

列出项目

你能列出我所有的Backlog项目吗？

创建新问题

在PROJECT-KEY项目中创建一个高优先级的bug问题，标题为“修复登录页面错误”

获取项目详情

显示PROJECT-KEY项目的详细信息

与Git仓库协作

列出PROJECT-KEY项目中的所有Git仓库

管理Pull Requests

显示PROJECT-KEY项目中repo-name仓库的所有打开的pull requests

在PROJECT-KEY项目中从feature/new-feature分支到main分支创建一个新的pull request

监视项

显示我正在监视的所有项

使用字段选择

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

显示PROJECT-KEY项目的详细信息，但只包括名称、键和描述字段

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对象，其中工具名称作为键，新的描述作为值。
例如：

json
{
"TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "替代描述",
"TOOL_CREATE_PROJECT_DESCRIPTION": "在Backlog中创建新项目"
}

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

1. 环境变量（例如，BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION）
2. .backlog-mcp-serverrc.json中的条目 - 支持的配置文件格式：.json, .yaml, .yml
3. 内置回退值（英文）

示例配置：

json
{
"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标志的二进制文件来导出现有的默认翻译（包括任何覆盖）。

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

示例：

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

或

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

使用日语翻译模板

提供了一个示例日语配置文件：

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

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

然后您可以根据需要编辑文件来自定义描述。### 使用环境变量
另外，您可以通过环境变量来覆盖工具描述。

环境变量的名称基于工具键，并以 BACKLOG_MCP_ 为前缀且全部大写。

示例：
要覆盖 TOOL_ADD_ISSUE_COMMENT_DESCRIPTION：

json
{
"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": "一个替代描述"
}
}
}
}

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

环境变量总是优先于配置文件。

开发

运行测试

bash
npm test

添加新工具

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

命令行选项

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

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

示例：
bash
node build/index.js --optimize-response --max-tokens=100000

许可证

本项目采用 MIT 许可证。

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