plane-mcp-server

一个用于自托管 Plane（Community Edition） 的 MCP（Model Context Protocol）服务器。它为 Claude 提供 56 个工具，涵盖项目、工作项、状态、标签、周期、模块、评论、活动历史、链接、成员和收件箱分类，足以在本地聊天会话中充当您 Plane 工作区中每个项目的项目经理。

基于 Plane 的公共 REST API（/api/v1）构建，文档见 developers.plane.so。Community Edition 涵盖项目、工作项、周期、模块、收件箱以及状态/标签——本服务器仅覆盖这些功能。史诗、倡议、团队空间和客户是 Plane Commercial/Cloud 专属功能，有意不包含在内。

设置

1. 生成 Plane API 密钥

在您的 Plane 实例中：个人设置 → 个人访问令牌 → 添加个人访问令牌。

2. 安装依赖并构建

cd plane-mcp-server
npm install
npm run build

3. 配置环境变量

将 .env.example 复制为 .env 作为参考，但请注意：MCP 客户端（Claude Desktop、Claude Code）直接在配置中传递环境变量，而不是通过本进程加载的 .env 文件。

4. 添加到您的 MCP 客户端

Claude Code（claude mcp add 或编辑 .mcp.json）：

{
  "mcpServers": {
    "plane": {
      "command": "node",
      "args": ["/absolute/path/to/plane-mcp-server/dist/index.js"],
      "env": {
        "PLANE_BASE_URL": "https://plane.mycompany.com",
        "PLANE_API_KEY": "plane_api_xxxxxxxxxxxxxxxxxxxx",
        "PLANE_WORKSPACE_SLUG": "acme"
      }
    }
  }
}

Claude Desktop（claude_desktop_config.json）：与上述相同的 mcpServers 块。

编辑配置后重启客户端。您应该会看到 plane 服务器连接并显示 56 个可用工具。

Related MCP server: plane-selfhost-mcp

它能做什么

• 项目 — 列出/获取/创建/更新/归档/删除，同时跟踪工作区中的每个项目。

• 工作项（问题） — 完整的增删改查，按 UUID 或人类可读标识符（ENG-123）查找，自由文本搜索，以及高级结构化筛选搜索（按状态、优先级、负责人、标签）。

• 状态与标签 — 检查和管理每个项目的工作流列和标签。

• 周期（冲刺） — 创建/更新/删除，分配或移除工作项，读取进度计数以进行状态报告。

• 模块 — 与周期相同的生命周期，用于长期运行的功能分组。

• 评论与活动 — 读写讨论线程，读取工作项上字段变更的审计轨迹。

• 链接 — 将 PR/文档/设计附加到工作项。

• 成员 — 将人员的姓名/邮箱解析为 UUID，为项目配备人员，更改角色。

• 收件箱 — 在请求进入待办事项之前进行分类（接受/拒绝/搁置/重复）。

每个 list/get 工具都接受 response_format: "markdown" | "json"（默认为 markdown，便于阅读；json 用于进一步的程序化使用），每个需要工作区的工具在您配置了 PLANE_WORKSPACE_SLUG 时会默认使用它，因此大多数调用只需要 project_id。

未实现

有意排除在外以保持功能面聚焦且仅限 CE：文件/附件上传、页面、估算、时间跟踪（工作日志）、自定义工作项类型/属性，以及仅限商业版的史诗/倡议/团队空间/客户/IDP 同步 API。这些可以稍后按照 src/tools/ 中的相同模式添加。

典型的多项目 PM 会话

1. plane_list_projects — 查看工作区中的所有内容。

2. 在活动项目上使用 plane_advanced_search_work_items 并带优先级/状态筛选 — 找出紧急事项。它是项目范围的，因此每个项目调用一次即可覆盖整个工作区。

3. 在活动项目上使用 plane_list_cycles，然后使用 plane_list_cycle_work_items — 检查当前冲刺状态。

4. plane_update_work_item — 在状态之间移动项目、重新分配、重新设置优先级。

5. plane_add_work_item_comment — 留下状态备注。

6. plane_list_intake_issues + plane_update_intake_issue — 清空分类队列。

开发

npm run dev     # tsx watch, runs src/index.ts directly
npm run build   # compile to dist/
npm start       # run compiled dist/index.js

使用 MCP Inspector 进行测试：

npx @modelcontextprotocol/inspector node dist/index.js

（在 Inspector 的环境面板中设置 PLANE_BASE_URL / PLANE_API_KEY / PLANE_WORKSPACE_SLUG。）

关于端点稳定性的说明

本服务器基于 Plane 的托管 API 文档（developers.plane.so）以及文档化的自托管行为构建——自托管实例共享相同的 /api/v1 接口，但具体行为可能因 Plane 版本而略有差异。如果某个不太常用的工具（例如 plane_advanced_search_work_items 筛选语法）在您的实例上返回 400/404，请优先使用更简单的 plane_list_work_items / plane_list_states / plane_list_labels 工具并在客户端进行筛选，或者如果您的实例暴露了 API 文档，请查看 <your-plane-url>/api/。