Backlog MCP Server 使用说明

项目简介

Backlog MCP Server 是一个专门为 LLM 应用设计的 MCP 服务器，它充当 LLM 与 Backlog 项目管理工具之间的桥梁。通过此服务器，LLM 客户端（如 Cursor 编辑器或 Claude Desktop）能够安全、便捷地访问和利用 Backlog 系统中的项目数据，例如 issues 和 wikis。该服务器专注于提供对 Backlog 信息的只读访问能力，项目范围固定，简化了配置和使用流程。

主要功能点

Issues (课题/问题) 数据访问: 提供工具检索、查看 Backlog 项目中的 issue 信息，包括 issue 列表、issue 详情、issue 评论和附件。
Wikis 数据访问: 提供工具检索、查看 Backlog 项目中的 Wiki 页面信息，包括 Wiki 页面列表、Wiki 页面详情和附件。
MCP 协议标准支持: 完全遵循 Model Context Protocol 协议，确保与各种 MCP 客户端的兼容性和互操作性。
Stdio 传输协议: 使用 Stdio 作为默认传输协议，简化部署和运行方式。
工具注册与管理: 预注册了一系列用于访问 Backlog 数据的工具，方便 LLM 客户端直接调用。

安装步骤

安装依赖: 确保你的开发环境中已安装 Bun。在项目根目录下运行 'bun install' 命令安装项目依赖。
```
bun install
```

配置环境变量: 复制 '.env.example' 文件并重命名为 '.env'。根据你的 Backlog 账户信息，填写以下环境变量：

BACKLOG_API_KEY=你的_Backlog_API密钥
BACKLOG_SPACE_ID=你的_Backlog_空间ID
BACKLOG_PROJECT_ID=你的_Backlog_项目ID

请务必替换 '你的_Backlog_API密钥'、'你的_Backlog_空间ID' 和 '你的_Backlog_项目ID' 为你实际的 Backlog API 密钥、空间 ID 和项目 ID。你需要在 Backlog 后台生成 API 密钥。

服务器配置 (mcp.json)

为了让 MCP 客户端（如 Cursor 或 Claude Desktop）连接到 Backlog MCP Server，你需要配置 'mcp.json' 文件。以下是配置示例，你需要根据你的实际情况进行调整。

将以下 JSON 内容保存为 'mcp.json' 文件，并放置在 MCP 客户端指定的配置路径下（例如，Cursor 的项目配置为 '.cursor/mcp.json'，全局配置路径请参考 README.md）。

{
  "mcpServers": {
    "backlog": {  // Server Name，客户端用以识别和引用
      "command": "npx",  // 启动服务器的命令，这里使用 npx 运行 npm 包
      "args": ["@yh1715/backlog-mcp"], // 启动参数，这里指向 backlog-mcp npm 包
      "env": { // 环境变量配置，传递 Backlog API 密钥等敏感信息
        "BACKLOG_API_KEY": "你的_Backlog_API密钥", // 替换为你的 Backlog API 密钥
        "BACKLOG_SPACE_ID": "你的_Backlog_空间ID",  // 替换为你的 Backlog 空间 ID
        "BACKLOG_PROJECT_ID": "你的_Backlog_项目ID" // 替换为你的 Backlog 项目 ID
      }
    }
  }
}

配置说明:

'"mcpServers"': MCP 服务器配置的根节点。
'"backlog"': 自定义的服务器名称，用于在客户端中引用。
'"command"': 启动服务器的可执行命令。'npx' 用于运行本地或全局安装的 npm 包。
'"args"': 传递给 'command' 的参数。'["@yh1715/backlog-mcp"]' 指示 'npx' 运行名为 '@yh1715/backlog-mcp' 的 npm 包，这实际上是项目在 'package.json' 中配置的包名，会被发布到 npm 仓库。
'"env"': 环境变量配置，用于传递服务器运行所需的敏感信息，例如 Backlog API 密钥和 ID。请务必替换示例值为你自己的实际值。

注意: 'command' 和 'args' 的配置需要确保 MCP 客户端能够正确找到并执行 Backlog MCP Server。如果你选择本地开发运行，并且没有将项目发布为 npm 包，'args' 可能需要调整为指向本地的 'src/index.ts' 文件，例如 '"args": ["bun", "run", "src/index.ts"]'，但这取决于你的具体环境和客户端的配置方式。但根据提供的 'mcp.json' 示例，以及 'README.md' 中 "npx @yh1715/backlog-mcp" 的描述，客户端期望的是直接运行已发布的 npm 包。

基本使用方法

启动 MCP Server: 在配置好 'mcp.json' 后，当 MCP 客户端（如 Cursor 或 Claude Desktop）启动时，它会根据 'mcp.json' 中的配置自动尝试连接到 Backlog MCP Server。 你无需手动运行 'bun run src/index.ts' 启动服务器，客户端会根据 'mcp.json' 的配置自动启动。
在 MCP 客户端中使用工具: 在 Cursor 或 Claude Desktop 中，当需要访问 Backlog 数据时，Agent 将能够识别并调用 Backlog MCP Server 提供的工具。你可以通过自然语言指令指示 Agent 使用例如 'backlog.issues.list' (获取 issue 列表), 'backlog.wikis.get' (获取 Wiki 详情) 等工具来查询 Backlog 信息。

具体的工具调用方式和参数，请参考 "利用可能なツール" 部分的描述，并在 MCP 客户端的 Agent 交互界面中进行操作。

注意: 由于该 Backlog MCP Server 实现为项目固定且只读，所有操作都将限定在你在 '.env' 文件和 'mcp.json' 中配置的 'BACKLOG_PROJECT_ID' 指定的项目范围内，并且仅提供数据读取功能。

关键词