回溯记录-MCP服务器

Name: 回溯记录-MCP服务器
Author: nulab

作者：nulab117 星标更新：2025-11-18

安装使用来源：spider==github.com

项目介绍

Backlog MCP Server

Last Commit

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

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

功能

项目工具（创建、读取、更新、删除）
问题跟踪和评论（创建、更新、删除、列表）
版本/里程碑管理（创建、读取、更新、删除）
维基页面支持
Git仓库和拉取请求工具
通知工具
GraphQL风格的字段选择以优化响应
对大型响应进行令牌限制

快速开始

要求

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

方案1：通过Docker安装

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

打开MCP设置
导航到MCP配置部分
添加以下配置：

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

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

✅ 如果您无法使用--pull always，可以手动更新镜像：

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

方案2：通过npx安装

您也可以直接使用npx运行服务器而不克隆存储库。这是一种无需完整安装即可运行服务器的便捷方式。

打开MCP设置
导航到MCP配置部分
添加以下配置：

{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": [
        "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密钥。

方案3：手动设置（Node.js）

克隆并安装：

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

工具配置

您可以使用--enable-toolsets命令行标志或ENABLE_TOOLSETS环境变量来选择性地启用或禁用特定的工具集。这允许更好地控制提供给AI代理的工具，并有助于减少上下文大小。

可用工具集

以下工具集可用（默认情况下当使用"all"时启用）：

工具集	描述
`space`	管理Backlog空间设置和一般信息的工具
`project`	管理项目、类别、自定义字段和问题类型的工具
`issue`	管理问题及其评论、版本里程碑的工具
`wiki`	管理维基页面的工具
`git`	管理Git仓库和拉取请求的工具
`notifications`	管理用户通知的工具
`document`	查看文档和文档树的工具

指定工具集

您可以按以下方式控制工具集激活：

通过CLI使用：

--enable-toolsets space,project,issue

或者通过环境变量：

ENABLE_TOOLSETS="space,project,issue"

如果指定为“all”，则将启用所有可用工具集。这也是默认行为。

使用选择性工具集在工具集列表过大或某些工具导致性能问题时可能非常有用。在这种情况下，禁用未使用的工具集可能会提高稳定性。

🧩 提示：强烈推荐使用project工具集，因为许多其他工具依赖于项目数据作为入口点。

动态工具集发现（实验性）

如果您使用MCP服务器与AI代理一起工作，可以在运行时启用工具集的动态发现：

通过CLI启用：

--dynamic-toolsets

或者通过环境变量：

-e DYNAMIC_TOOLSETS=1 \

启用动态工具集后，LLM可以通过工具接口按需列出和激活工具集。

可用工具

工具集：`space`

管理Backlog空间设置和一般信息的工具。

get_space：返回关于Backlog空间的信息。
get_users：返回Backlog空间中的用户列表。
get_myself：返回关于已认证用户的详细信息。

工具集：`project`

管理项目、类别、自定义字段和问题类型的工具。

get_project_list：返回项目列表。
add_project：创建新项目。
get_project：返回特定项目的详细信息。
update_project ：更新现有项目。
delete_project：删除项目。

工具集：`issue`

管理问题、其评论以及相关项（如优先级、类别、自定义字段、问题类型、解决方案和关注列表）的工具。

get_issue：返回特定问题的详细信息。
get_issues：返回问题列表。
count_issues：返回问题数量。
add_issue：在指定项目中创建新问题。
update_issue：更新现有问题。
delete_issue：删除问题。
get_issue_comments：返回问题的评论列表。
add_issue_comment：向问题添加评论。
get_priorities：返回优先级列表。
get_categories：返回项目的类别列表。
get_custom_fields：返回项目的自定义字段列表。
get_issue_types：返回项目的类型列表。
get_resolutions：返回问题解决方案列表。
get_watching_list_items：返回用户关注的项目列表。
get_watching_list_count：返回用户关注的项目数量。
get_version_milestone_list：返回项目的版本里程碑列表。
add_version_milestone：为项目创建新的版本里程碑。
update_version_milestone：更新现有的版本里程碑。
delete_version_milestone：删除版本里程碑。

工具集：`wiki`

管理维基页面的工具。

get_wiki_pages：返回维基页面列表。
get_wikis_count：返回项目中的维基页面数量。
get_wiki：返回特定维基页面的详细信息。
add_wiki：创建新的维基页面。

工具集：`git`

管理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：更新拉取请求上的评论。

工具集：`notifications`

管理用户通知的工具。

get_notifications：返回通知列表。
get_notifications_count：返回通知数量。
reset_unread_notification_count：重置未读通知计数。
mark_notification_as_read：标记通知为已读。

工具集：`document`

管理Backlog项目中的文档和文档树的工具。

get_document_tree：返回项目的文档层次结构树，包括文件夹和文档。
get_documents：返回项目或文件夹中的文档扁平列表。
get_document：返回特定文档的详细信息，包括元数据、内容等。

使用示例

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

列出项目

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

创建新问题

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

获取项目详情

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

处理Git仓库

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

管理拉取请求

显示PROJECT-KEY项目中仓库“repo-name”的所有打开的拉取请求

从分支“feature/new-feature”到“main”在PROJECT-KEY项目中仓库“repo-name”创建一个新的拉取请求

关注项目

显示我正在关注的所有项目

i18n / 覆盖描述

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

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

{
  "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "另一种描述",
  "TOOL_CREATE_PROJECT_DESCRIPTION": "在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": "另一种描述"
      }
    }
  }
}

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

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

高级功能

工具名前缀

通过以下方式添加工具名前缀：

--prefix backlog_

或通过环境变量：

PREFIX="backlog_"

如果您在同一环境中使用多个MCP服务器或工具并且想要避免名称冲突，这特别有用。例如，get_project可以变为backlog_get_project以区分由其他服务提供的类似命名的工具。

响应优化及令牌限制

字段选择（GraphQL风格）

--optimize-response

或环境变量：

OPTIMIZE_RESPONSE=1

然后，仅请求所需字段：

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

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

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

优点：

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

令牌限制

大型响应自动限制以防止超过令牌限制：

默认限制：50,000个令牌
通过MAX_TOKENS环境变量可配置
超过限制的响应将被截断并附带消息

您可以更改此设置：

MAX_TOKENS=10000

如果响应超过限制，它将被截断并带有警告。

注意：这是尽力而为的缓解措施，而不是保证执行。

完整自定义配置示例

本节演示使用多个环境变量的高级配置。这些是实验性功能，可能不被所有MCP客户端支持。这不是MCP标准规范的一部分，应谨慎使用。

{
  "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/中创建一个新文件，遵循现有工具的模式
创建相应的测试文件
将新工具添加到src/tools/tools.ts
构建并测试您的更改

命令行选项

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

--export-translations：导出所有翻译键和值
--optimize-response：启用GraphQL风格的字段选择
--max-tokens=NUMBER：设置响应的最大令牌限制
--prefix=STRING：可选字符串前缀，附加到所有工具名（默认：“”）
--enable-toolsets <toolsets...>：指定要启用的工具集（逗号分隔或多个参数）。默认为“all”。示例：--enable-toolsets space,project 或 --enable-toolsets issue --enable-toolsets git 可用工具集：space，project，issue，wiki，git，notifications。

示例：

node build/index.js --optimize-response --max-tokens=100000 --prefix="backlog_" --enable-toolsets space,issue

许可证

本项目根据MIT许可证授权。

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