Plane MCP Server

Plane MCP 服务

一个适用于 Plane 的模型上下文协议服务。为 AI Agent 提供读取和管理项目、工作项、周期、模块、版本、客户等内容的工具。

基于 FastMCP 和官方的 plane-sdk 构建。

• 30 个工具，每种 Plane 资源一个，涵盖 207 项操作
• 本地或远程——stdio、可流式传输的 HTTP、SSE
• OAuth 或 API 密钥身份验证

快速开始

从 Plane 获取 API 密钥：工作区设置 → API 令牌。

将以下内容添加到 MCP 客户端的配置中：

{
  "mcpServers": {
    "plane": {
      "command": "uvx",
      "args": ["plane-mcp-server", "stdio"],
      "env": {
        "PLANE_API_KEY": "<your-api-key>",
        "PLANE_WORKSPACE_SLUG": "<your-workspace-slug>"
      }
    }
  }
}

uvx 无需安装。需要 Python 3.10+。

对于可自托管的 Plane，请添加 "PLANE_BASE_URL": "https://plane.example.com"。

传输方式

stdio — 本地

作为 MCP 客户端的子进程运行。配置如上所示；需要 PLANE_API_KEY 和 PLANE_WORKSPACE_SLUG。

PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... uvx plane-mcp-server stdio

使用 OAuth 的 HTTP — 托管

https://mcp.plane.so/http/mcp

连接时会处理 OAuth 流程；配置中无需填写凭据。对于不支持原生远程 MCP 的客户端，可使用 mcp-remote 桥接：

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
    }
  }
}

需要 Node.js 22+。

使用个人访问令牌的 HTTP — 托管

https://mcp.plane.so/http/api-key/mcp

Header	值
Authorization	Bearer <PAT>
X-Workspace-slug	<workspace-slug>

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.plane.so/http/api-key/mcp"],
      "headers": {
        "Authorization": "Bearer <PAT>",
        "X-Workspace-slug": "<workspace-slug>"
      }
    }
  }
}

SSE — 已弃用

https://mcp.plane.so/sse 仅为向后兼容而维护。请改用 HTTP 传输方式。

工具

该服务提供 30 个工具，每种资源一个。每个工具都接受一个用于选择操作的 action 参数：

workitem(action="create", project_id=..., name="Fix login")
workitem(action="list", project_id=..., pql='state__group = "started"')
cycle(action="archive", project_id=..., cycle_id=...)

每个工具的描述都会列出其操作及必需和可选参数，因此调用时可直接查阅目录了解用法。

→ 完整的工具和操作参考

查询工作项

列表、计数和搜索操作都支持 Plane 的查询语言 PQL：

workitem(action="list", project_id=..., pql='state__group = "started" AND priority = "urgent"')
workitem(action="count", pql='assignees__id = "<member id>"', group_by="state_id")

调用 get_pql_reference 可查看完整语法、运算符和示例。

从按操作拆分的工具升级

早期版本为每项 API 操作提供一个工具。现有集成仍可正常工作：原先 177 个名称中有 169 个仍会解析到合并后的工具，因此调用 create_work_item 或 list_cycles 的已保存提示词或脚本无需修改。这些名称不再公布，并继续使用其发布时的参数名称（work_item_id，而不是 workitem_id）。

有 7 个名称可通过一个参数在两项操作之间进行选择（manage_project_archive(archive=False)），无法通过一个工具与操作组合来复现；调用这些名称时会告知其替代方案。get_pql_reference 保持不变。

配置

身份验证

变量	必需场景	用途
PLANE_API_KEY	stdio	API 密钥
PLANE_WORKSPACE_SLUG	stdio	目标工作区
PLANE_BASE_URL	可选	Plane API URL（默认值为 https://api.plane.so）

远程传输方式会在连接中携带凭据——通过 OAuth 流程或 PAT 标头——因此无需设置这些变量。

附件上传的出站代理

HTTP_PROXY / HTTPS_PROXY / NO_PROXY（及其小写形式）适用于从 URL 上传附件时的抓取（upload_from_url）。当代理适用于某个请求时，该请求的 SSRF 防护由代理负责，而非此服务：服务本身不会固定或验证目标解析后的地址，因为代理会独立连接并解析目标。请据此配置 NO_PROXY 和代理的出站策略。

自行托管服务本身：

变量	用途
PLANE_INTERNAL_BASE_URL	服务器间调用使用的内部 URL，优先于 PLANE_BASE_URL
REDIS_URL	OAuth 令牌存储使用的单个连接 URL（TLS 使用 redis:// 或 rediss://）；优先于主机/端口
REDIS_HOST / REDIS_PORT	OAuth 令牌存储；未设置时回退到内存存储
PLANE_OAUTH_PROVIDER_*	OAuth 客户端凭据和基础 URL
MCP_PATH_PREFIX	HTTP 路由的路径前缀，适用于挂载在代理后面的情况 — /plane 会提供 /plane/http/mcp

OAuth 重定向 URI

OAuth 传输会根据允许列表验证每个客户端的重定向 URI。 常见客户端（Cursor、VS Code、Claude.ai、ChatGPT connectors、localhost）默认允许。

无需发布新版本即可接入新客户端，只需追加模式：

export PLANE_OAUTH_ALLOWED_REDIRECT_URIS="https://newclient.com/cb,https://other.app/oauth/*"

* 可匹配任意端口、路径段或子域名。请固定主机，只对端口或路径使用通配符。

日志记录

采用结构化 JSON。每次工具调用都会记录名称、耗时、状态，以及（如果可用）不透明的用户 ID 和工作区 slug。

export LOG_USER_INFO=false    # also log the display name (PII);
export LOG_PAYLOADS=false    # keep request payloads out of logs; default true

只有 OAuth 和 PAT 传输会携带显示名称；stdio 不受影响。

开发

git clone https://github.com/makeplane/plane-mcp-server
cd plane-mcp-server
uv pip install -e ".[dev]"

针对工作区运行服务：

PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... python -m plane_mcp stdio
python -m plane_mcp http            # port 8211

测试、格式化、代码检查：

pytest                              # no network or credentials needed
ruff format plane_mcp/ tests/       # line length 120
ruff check plane_mcp/ tests/        # rules E, F, I, UP, B

测试套件完全离线运行——每个资源的每项操作都会针对一个替身执行，该替身会将每次调用与真实的 plane-sdk 签名进行校验。请参阅 plane_mcp/tools/README.md。

只有在指定运行中的服务后，才会运行实时集成测试：

export PLANE_TEST_API_KEY=... PLANE_TEST_WORKSPACE_SLUG=...
export PLANE_TEST_MCP_URL=http://localhost:8211    # optional; this is the default
pytest tests/test_integration.py -v

这些测试会向该工作区写入真实数据。

仓库布局

路径	内容
plane_mcp/__main__.py	入口点；从 argv[1] 选择传输方式
plane_mcp/server.py	每种传输方式对应一个工厂
plane_mcp/client.py	将凭据解析为 plane-sdk 客户端
plane_mcp/auth/	OAuth 提供方和请求头认证
plane_mcp/tools/	工具集：每个 Plane 资源对应一个模块
plane_mcp/toolkit/	工具集的共享构建模块
plane_mcp/pql_reference.py	提供给模型的 PQL 语法参考

贡献

欢迎提交拉取请求。提交前请运行 pytest 和 ruff check；新增工具应遵循 plane_mcp/tools/README.md 中说明的不变式。

请参阅 CONTRIBUTING.md 和 CODE_OF_CONDUCT.md。

从 Node.js 服务迁移

@makeplane/plane-mcp-server（Node.js）已弃用且不再维护。此 Python 实现将取代它。

Node.js	Python
PLANE_API_KEY	PLANE_API_KEY
PLANE_API_HOST_URL	PLANE_BASE_URL
PLANE_WORKSPACE_SLUG	PLANE_WORKSPACE_SLUG

请将 command 和 args 替换为快速开始中的 stdio 配置。

许可证

MIT — 请参阅 LICENSE。