Backlog MCP Server

Backlog MCP 服务

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

用于与 Backlog API 交互的模型上下文协议（MCP）服务。该服务可通过 Claude Desktop / Cline / Cursor 等 AI Agent，提供管理 Backlog 中的项目、问题、Wiki 页面等内容的工具。

功能

• 项目工具（创建、读取、更新、删除）
• 问题跟踪和评论（创建、更新、删除、列出）
• 版本/里程碑管理（创建、读取、更新、删除）
• Wiki 页面支持
• Git 仓库和拉取请求工具
• 通知工具
• 字段选择，优化响应
• 限制大型响应的令牌数量

快速开始

要求

• Docker
• 可访问 API 的 Backlog 帐户
• Backlog 帐户的 API 密钥

选项 1：通过 Docker 安装

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

1. 打开 MCP 设置
2. 前往 MCP 配置部分
3. 添加以下配置：

{
  "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 直接运行服务，无需克隆仓库。这种方式无需完整安装，使用起来很方便。

1. 打开 MCP 设置
2. 前往 MCP 配置部分
3. 添加以下配置：

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

1. 克隆并安装：

   git clone https://github.com/nulab/backlog-mcp-server.git
   cd backlog-mcp-server
   pnpm install
   pnpm run build
   

2. 根据模板创建 .env 并设置必需变量：

cp .env.example .env

在 .env 中设置以下值：

• BACKLOG_DOMAIN=your-domain.backlog.com
• BACKLOG_API_KEY=your-api-key

3. 在本地运行：

pnpm run dev

4. 设置要用作 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"
      }
    }
  }
}

HTTP 传输（Streamable HTTP）

默认情况下，服务使用 stdio。若要改用 MCP Streamable HTTP 传输（通过 HTTP 传输 JSON-RPC，工具与 stdio 相同），请使用 --transport http 启动，或设置 MCP_TRANSPORT=http。

pnpm run build
MCP_TRANSPORT=http MCP_HTTP_PORT=3333 node build/index.js

• **端点：**在 http://<host>:<port><path> 上使用 POST（以及用于服务端发起流的 GET），默认路径为 /mcp。
• **协议：**MCP 2026-07-28。该协议无状态：没有 initialize 握手，也没有 mcp-session-id 标头。客户端在每个请求的 _meta 中发送其元数据，并通过 server/discover 发现功能。Streamable HTTP 还要求提供 Mcp-Method 标头（在 tools/call 时还需提供 Mcp-Name）。
• **向后兼容性：**仍可通过同一端点以无状态方式服务使用 2025-11-25 及更早版本的客户端。由于不保留会话，2025 版的会话操作（携带 mcp-session-id 的 GET / DELETE）会返回 405。
• **安全性：**默认绑定地址为 127.0.0.1。仅绑定到回环地址时，Host 和 Origin 都会针对本地主机地址进行验证（防止 DNS 重绑定）。在反向代理之后运行时，请设置 --http-allowed-hosts 为公开主机名；这会关闭默认的本地 Origin 检查，因为浏览器客户端的 Origin 是其自身站点，而非此服务的主机名。添加 --http-allowed-origins，以限制可访问服务的客户端来源。若未配置身份验证和 TLS，请勿将 HTTP 端口暴露给不可信网络；这会允许通过 MCP 工具充分使用你的 Backlog API 密钥。

环境变量（同时设置时，CLI 标志优先）：

变量	描述
MCP_TRANSPORT	stdio（默认）或 http
MCP_HTTP_HOST	绑定地址（默认 127.0.0.1）
MCP_HTTP_PORT	端口（默认 3333）
MCP_HTTP_PATH	URL 路径（默认 /mcp）
MCP_HTTP_JSON_RESPONSE	设为 true 时优先使用 JSON 响应而非 SSE（仅适用于 2026-07-28 客户端）
MCP_HTTP_ALLOWED_HOSTS	以逗号分隔的允许 Host 主机名（不区分端口）。绑定到 0.0.0.0 时必需；也可用于绕过代理后的回环地址绑定限制（防止 DNS 重绑定）
MCP_HTTP_ALLOWED_ORIGINS	以逗号分隔的允许的浏览器客户端 Origin 主机名。仅绑定到回环地址时，默认使用本地主机地址；其他情况下默认不检查 Origin

OAuth 2.0 身份验证（远程 MCP）

通过网络公开 MCP 服务时，可以启用 OAuth 2.0 身份验证，让每位用户使用自己的 Backlog 账户进行身份验证，而不是共用一个 API 密钥。

该服务通过同时充当 MCP 客户端的 OAuth 授权服务器和 Backlog 的 OAuth 客户端，实现了 MCP 第三方授权流程。

前置条件

1. 在你的 Backlog 空间中注册 OAuth 应用：

   • 前往你的 Backlog 空间 → 个人设置 → 注册应用
   • 将 重定向 URI 设置为 <MCP_SERVER_BASE_URL>/callback（例如，https://mcp.example.com/callback）
   • 记下 客户端 ID 和 客户端密钥

2. 设置以下环境变量（除 BACKLOG_DOMAIN 外）：

变量	说明
BACKLOG_OAUTH_CLIENT_ID	Backlog 应用的 OAuth 客户端 ID
BACKLOG_OAUTH_CLIENT_SECRET	Backlog 应用的 OAuth 客户端密钥
MCP_SERVER_BASE_URL	MCP 服务的公开 URL（例如，https://mcp.example.com）

**注意：**启用 OAuth 后，无需设置 BACKLOG_API_KEY——每位用户都使用自己的 Backlog 账号进行身份验证。

示例

BACKLOG_DOMAIN=your-space.backlog.com \
BACKLOG_OAUTH_CLIENT_ID=your-client-id \
BACKLOG_OAUTH_CLIENT_SECRET=your-client-secret \
MCP_SERVER_BASE_URL=https://mcp.example.com \
node build/index.js --transport http --http-host 0.0.0.0 --http-port 3333 \
  --http-allowed-hosts mcp.example.com

实际上，绑定到 0.0.0.0 时需要使用 --http-allowed-hosts：若不设置，则没有 DNS 重绑定保护，且服务会在启动时记录一条警告。

启用 OAuth 后，服务会自动提供以下 OAuth 端点：

端点	说明
GET /.well-known/oauth-authorization-server	OAuth 授权服务器元数据（RFC 8414）
GET /.well-known/oauth-protected-resource/mcp	OAuth 受保护资源元数据（RFC 9728）
POST /register	动态客户端注册（RFC 7591）
GET /authorize	授权端点（重定向到 Backlog OAuth）
GET /callback	Backlog OAuth 回调
POST /token	令牌端点（授权码和刷新令牌）

支持 MCP 授权规范的 MCP 客户端会自动使用这些端点。

POST /register 会限制客户端可注册的重定向 URI。环回 URI（http://localhost、http://127.0.0.1、http://[::1]）用于让运行在用户设备上的应用接收授权码；声明 "application_type": "native" 的客户端可以使用该 URI；若未声明此字段，则仅当其所有重定向 URI 都是环回 URI 时才可使用。声明 "application_type": "web" 的客户端，或者未声明应用类型却混用远程 https: URI 和环回 URI 的客户端，会因 invalid_client_metadata 而被拒绝。

限制：

• OAuth 模式目前仅支持一个 Backlog 组织，与多组织配置不兼容。
• 客户端注册信息和令牌存储在内存中，服务重启后会丢失。

工具配置

你可以使用命令行标志 --enable-toolsets 或环境变量 ENABLE_TOOLSETS，选择性地启用或禁用特定的工具集。这样可以更好地控制 AI Agent 可用的工具，并有助于缩减上下文大小。

可用工具集

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

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

指定工具集

可以通过以下方式控制工具集的启用：

通过 CLI 使用：

--enable-toolsets space,project,issue

或通过环境变量：

ENABLE_TOOLSETS="space,project,issue"

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

如果工具集列表对 AI Agent 来说过于庞大，或某些工具导致性能问题，选择性启用工具集会很有帮助。在这种情况下，停用未使用的工具集可能会提高稳定性。

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

可用工具

工具集：space

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

• get_space：返回 Backlog 空间的信息。
• get_users：返回 Backlog 空间中的用户列表。
• get_myself：返回已通过身份验证的用户信息。

工具集：project

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

• get_project_list：返回项目列表。
• add_project：创建新项目。
• get_project：返回特定项目的信息。
• get_project_users：返回特定项目中的用户列表。
• update_project：更新现有项目。

工具集：issue

用于管理问题、问题评论及相关项目的工具，例如优先级、类别、自定义字段、问题类型、解决结果和关注列表。

• get_issue：返回特定问题的信息。
• get_issue_attachment：下载问题的一个附件。返回图片或嵌入式资源内容，也可通过 format: "base64" 以 base64 格式返回。
• get_issues：返回问题列表。
• count_issues：返回问题数量。
• add_issue：在指定项目中创建新问题。
• update_issue：更新现有问题。
• delete_issue：删除问题。
• get_issue_comments：返回问题评论列表。
• add_issue_comment：为问题添加评论。
• update_issue_comment：更新问题评论。
• get_related_issues：返回与特定问题相关的问题列表。
• add_related_issue：将一个问题关联到另一个问题。
• remove_related_issue：移除问题与相关问题之间的关联。
• get_priorities：返回优先级列表。
• get_categories：返回项目的类别列表。
• add_category：为项目创建新类别。
• get_custom_fields：返回项目的自定义字段列表。
• get_issue_types：返回项目的问题类型列表。
• get_resolutions：返回问题解决结果列表。
• get_watching_list_items：返回用户的关注项目列表。
• get_watching_list_count：返回用户关注的项目数量。
• add_watching：关注问题。
• update_watching：更新现有关注备注。
• delete_watching：取消关注问题。
• mark_watching_as_read：将关注项标记为已读。
• get_version_milestone_list：返回项目的版本里程碑列表。
• add_version_milestone：为项目创建新的版本里程碑。
• update_version_milestone：更新现有版本里程碑。
• delete_version_milestone：删除版本里程碑。

工具集：wiki

用于管理 Wiki 页面。

• get_wiki_pages：返回 Wiki 页面列表。
• get_wikis_count：返回项目中的 Wiki 页面数量。
• get_wiki：返回特定 Wiki 页面的信息。
• add_wiki：创建新的 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：返回项目文档的层级树，包括文件夹和 ne
• get_documents：返回项目或文件夹中的文档平面列表。
• get_document_comments：返回文档评论，包括回复。
• get_document：返回特定文档的详细信息，包括元数据、内容和

使用示例

在 AI Agent 中配置 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

覆盖工具描述

你可以在主目录中创建 .backlog-mcp-serverrc.json 文件，以覆盖工具描述。

这些字符串几乎都是模型在决定调用哪个工具以及如何填写参数时读取的工具和参数描述。因此，覆盖这些描述是引导工具选择的一种方式，例如消除两个相似工具之间的歧义，或添加团队遵循的规则，而不是改变你收到的回答所使用的语言。无论这些描述使用哪种语言，模型都会使用你提问时所用的语言回答。

少数键对应的是验证错误消息（例如 PROJECT_ID_OR_KEY_REQUIRED）。调用被拒绝时，这些消息会作为工具结果返回，因此模型的回复中可能会包含它们。

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

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

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

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

在每个层级中，空值或非字符串值都会被忽略，并使用内置默认值。

配置示例：

{
  "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-descriptions 标志的二进制文件，导出当前描述（包括任何覆盖内容）。此标志之前名为 --export-translations；旧名称仍可使用，但会显示弃用提示，并将在未来版本中移除。

此操作会打印构建工具列表时解析的每个键及其当前值，包括你进行的所有自定义设置。其中涵盖所有工具和参数描述，也是查找键名的实用方法。

验证错误消息不在其中，因为只有在调用实际被拒绝时才会解析这些键。它们仍可按相同规则覆盖；你需要从源代码中读取这些键。

示例：

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

或

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

使用环境变量

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

环境变量名称基于工具键，添加 BACKLOGMCP 前缀，并转换为大写。

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

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

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

高级功能

工具名称前缀

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

--prefix backlog_

或通过环境变量：

PREFIX="backlog_"

如果你在同一环境中使用多个 MCP 服务或工具，并希望避免名称冲突，这项功能尤其有用。例如，get_project 可以变为 backlog_get_project，以便与其他服务提供的同名工具区分开来。

响应优化与 Token 限制

响应压缩

工具结果会在返回前进行压缩。此功能始终启用，适用于除 get_issue_attachment 之外的所有工具；get_issue_attachment 会返回文件本身：

• 结果中的嵌套用户（createdUser、assignee、stars[].presenter、通知的 sender 等）会缩减为 id、userId 和 name。作为结果本身的用户（get_myself、get_users 或 get_project_users 的各项）则会完整返回。
• 嵌套项目（每项活动和通知中的 project）会缩减为 id、projectKey 和 name；嵌套问题（拉取请求或通知中的 issue）会缩减为 id、issueKey、summary 和 status。作为结果的项目或问题（get_project、get_issue、get_project_list 或 get_issues 的各项）会完整返回，get_watching_list_items 的每一项中的问题也会完整返回。
• 嵌套实体（状态、问题类型、类别、里程碑、自定义字段项等）会省略 color 和 displayOrder；嵌套里程碑还会省略 description。自行列出这些实体的工具（get_issue_types、get_categories、get_version_milestone_list 等）会完整返回它们。
• 值为 null、空字符串或空数组的字段会被省略。0、false 和 {} 会保留。此规则同样适用于 fields 中指定的字段：空字段会被省略，而不是以空值返回。
• JSON 返回时不带缩进。

字段选择

--optimize-response

或使用环境变量：

OPTIMIZE_RESPONSE=1

返回列表的工具随后会接受可选的 fields 参数：该参数是一个字段名列表，包含此工具结果中的顶层字段，并以枚举形式发布，因此如果指定的字段名不属于该工具，就会被拒绝，而不是忽略。返回单条记录的工具不支持此参数——该参数会增加每个会话的架构开销，而单条记录几乎没有可精简的内容。

get_project(projectIdOrKey: "PROJECT-KEY", fields: ["name", "key", "description"])

省略 fields 会返回完整结果。字段选择仅深入一层：指定对象或数组字段时，会完整返回该字段。

优点：

• 仅请求所需字段，减少响应大小
• 聚焦特定数据点
• 提升大型响应的性能

Token 限制

大型响应会自动受到限制，以防超过 Token 限制：

• 默认限制：50,000 个 Token
• 可通过 MAX_TOKENS 环境变量进行配置
• 超过限制的响应会被截断，并附带一条消息

你可以通过以下方式更改此设置：

MAX_TOKENS=10000

如果响应超过限制，就会被截断并显示警告。

注意：这是一种尽力而为的缓解措施，并不保证一定能强制执行。

日志记录

服务会将日志写入 stderr（在 stdio 传输中，stdout 承载 JSON-RPC 流）。

变量	描述
LOG_LEVEL	fatal、error、warn、info、debug、trace 或 silent。当 NODE_ENV 为 production 时，默认值为 error；未设置 NODE_ENV 时默认值也为 production。其他情况下默认值为 debug。如果值无法识别，系统会报告该情况并使用默认值。

NODE_ENV 仍会选择输出格式：只要值不是 production，且 pino-pretty 包可用，就会切换为便于人类阅读的输出。若要更改日志记录量，请使用 LOG_LEVEL，而不是 NODE_ENV，这样部署环境就能保留结构化 JSON：

pino-pretty 是开发依赖，因此已发布的 npm 包和容器映像都不包含该包。在这些环境中，无论 NODE_ENV 的值是什么，日志都会采用结构化 JSON；只有 LOG_LEVEL 设置会更改输出。

LOG_LEVEL=info node build/index.js --transport http

完整的自定义配置示例

本节演示如何使用多个环境变量进行高级配置。这些功能仍处于实验阶段，可能并不受所有 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"
      }
    }
  }
}

开发

运行测试

pnpm test

添加新工具

1. 在 src/tools/ 中创建一个新文件，遵循现有工具的模式
2. 创建对应的测试文件
3. 将新工具添加到 src/tools/tools.ts
4. 构建并测试你的更改

命令行选项

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

• --transport stdio|http：MCP 传输方式（默认值：stdio）。使用 http 启用 Streamable HTTP。
• --http-host、--http-port、--http-path：HTTP 绑定地址、端口和路径（默认值：127.0.0.1、3333、/mcp）。
• --http-json-response：优先返回 JSON，而非 SSE。仅适用于 2026-07-28 客户端；向后兼容的 2025-11-25 路径采用 SDK 的默认响应格式。
• --http-allowed-hosts：以逗号分隔的允许访问的 Host 主机名（不区分端口）。绑定到所有网络接口时，或通过反向代理使用环回地址绑定时，需要设置此项。
• --http-allowed-origins：以逗号分隔的允许访问的 Origin 主机名，供基于浏览器的客户端使用。在仅绑定到环回地址且未设置其他配置时，默认允许 localhost；其他情况下不检查 Origin。
• --export-descriptions：导出构建工具列表时解析的描述键和值。此选项原名为 --export-translations，该拼写仍可作为已弃用的别名使用，并将在未来版本中移除
• --optimize-response：为每个工具添加 fields 参数，以选择要返回的结果字段
• --max-tokens=NUMBER：设置响应的最大 token 数量
• --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

HTTP 示例：

node build/index.js --transport http --http-port 3333 --http-path /mcp

多组织支持

此服务可配置为通过单个 MCP 服务实例访问多个 Backlog 组织。

配置

为每个组织配置一组环境变量，并设置一个默认组织：

BACKLOG_DEFAULT_ORG=COMPANY_A
BACKLOG_ORG_COMPANY_A_DOMAIN=company-a.backlog.com
BACKLOG_ORG_COMPANY_A_API_KEY=your-company-a-api-key
BACKLOG_ORG_COMPANY_B_DOMAIN=company-b.backlog.com
BACKLOG_ORG_COMPANY_B_API_KEY=your-company-b-api-key

无论这些变量来自本地 .env 文件、Shell 环境，还是 MCP 客户端配置中的 env 块，此配置都适用。

MCP 配置示例：

{
  "env": {
    "BACKLOG_DEFAULT_ORG": "COMPANY_A",
    "BACKLOG_ORG_COMPANY_A_DOMAIN": "company-a.backlog.com",
    "BACKLOG_ORG_COMPANY_A_API_KEY": "your-company-a-api-key",
    "BACKLOG_ORG_COMPANY_B_DOMAIN": "company-b.backlog.com",
    "BACKLOG_ORG_COMPANY_B_API_KEY": "your-company-b-api-key"
  }
}

如果未设置多组织环境变量，服务将回退到现有的单组织配置：

BACKLOG_DOMAIN=your-domain.backlog.com
BACKLOG_API_KEY=your-api-key

工具用法

配置多组织环境变量后，所有常规工具都会接受可选的 organization 输入字段。提供此字段时，工具调用将路由到指定的 Backlog 组织。

在单组织模式下不会发布此字段，因为只有一个可供路由的组织。省略此字段可使每个 tools/list 响应减少约 8 KB 的工具架构数据。

示例：

{
  "organization": "COMPANY_B",
  "projectKey": "PROJECT"
}

如果省略 organization：

• 将使用 BACKLOG_DEFAULT_ORG 指定的组织
• 如果存在多组织环境变量但未设置 BACKLOG_DEFAULT_ORG，服务将在启动时失败

组织发现

在多组织模式下，服务会提供一个 list_organizations 工具，用于返回已配置的组织名称、域名以及默认组织。单组织模式下不会注册此工具。

响应示例：

[
  {
    "name": "COMPANY_A",
    "domain": "company-a.backlog.com",
    "isDefault": true
  },
  {
    "name": "COMPANY_B",
    "domain": "company-b.backlog.com",
    "isDefault": false
  }
]

说明

• 在多组织模式下，每个组织都必须定义 BACKLOG_ORG_<NAME>_DOMAIN 和 BACKLOG_ORG_<NAME>_API_KEY。
• <NAME> 部分是通过 organization 工具输入和 list_organizations 暴露的组织名称。

许可证

本项目采用 MIT License 授权。

请注意：本工具依据 MIT License 提供，不提供任何保证或官方支持。
请在查看内容并确认其适合您的需求后自行承担使用风险。
如果遇到任何问题，请通过 GitHub Issues 进行报告。