Plane MCP Server 是 Plane 的官方 Model Context Protocol 服务器，作用是给 AI 智能体提供工具，用来读取和管理 Plane 中的项目、工作项、周期、模块、发布、客户等内容，从而对 Plane 项目实现完整的 AI 自动化。它基于 FastMCP 与官方 plane-sdk 构建。
主要能力：服务器对外提供 30 个工具，每个工具对应一种 Plane 资源，合计覆盖 207 项操作。每个工具都接受一个 action 参数来选择具体操作；每个工具的描述中会列出其动作及必需和可选参数，因此调用时即可自行了解可用操作。查询工作项时，list、count 和 search 支持 PQL（Plane 的查询语言），要获取完整语法、运算符和示例可调用 get_pql_reference。
使用方式：需要先从 Plane 获取 API 密钥，路径为工作区设置（Workspace Settings）→ API tokens。然后将其加入 MCP 客户端的配置中。uvx 方式无需安装步骤，要求 Python 3.10+。若使用自托管 Plane，需要添加 "PLANE_BASE_URL": "https://plane.example.com"。该服务器也可作为 MCP 客户端的子进程运行，此配置需要 PLANE_API_KEY 和 PLANE_WORKSPACE_SLUG。还提供托管 HTTP 端点：OAuth 方式为 https://mcp.plane.so/http/mcp（连接时处理 OAuth 流程，配置中无需凭据）；对不支持原生远程 MCP 的客户端，可用 mcp-remote 桥接，需要 Node.js 22+。使用个人访问令牌的托管 HTTP 端点则为 https://mcp.plane.so/http/api-key/mcp。SSE 端点 https://mcp.plane.so/sse 仅为向后兼容而保留，建议改用 HTTP 传输。
从按操作划分的工具升级：早期版本为每个 API 操作提供一个工具。现有集成仍然可用，原有 177 个名称中的 169 个仍会解析到合并后的工具，因此调用 create_work_item 或 list_cycles 的已存提示或脚本无需修改。这些旧名称不再对外声明，并保留发布时的参数名（如 work_item_id，而非 workitem_id）。有七个名称原本通过参数在两个操作之间切换（如 manage_project_archive(archive=False)），这一行为无法用一个工具加动作的方式复现，调用时会提示其替代方式。get_pql_reference 保持不变。远程传输在连接中携带凭据（OAuth 流程或 PAT 请求头），不需要上述这些配置。
附件上传的出站代理：upload_from_url 从 URL 获取并上传附件时，会遵循 HTTP_PROXY / HTTPS_PROXY / NO_PROXY 及其小写形式。当代理适用于某请求时，该请求的 SSRF 控制由代理负责，而非本服务器；服务器本身不会固定或校验目标解析后的地址，因为代理会独立连接并解析目标。因此需要相应限定 NO_PROXY 和代理出口策略。
自托管服务器本身、OAuth 重定向 URI：OAuth 传输会根据允许列表校验每个客户端的重定向 URI。常见客户端（Cursor、VS Code、Claude.ai、ChatGPT connectors、localhost）默认被允许。要在不发布新版本的情况下接入新客户端，可追加匹配模式；其中 * 可匹配任意端口、路径段或子域，建议固定主机名，仅对端口或路径使用通配符。
日志方面：输出结构化 JSON。每次工具调用会记录名称、耗时、状态，并在可用时记录不透明的用户 id 和工作区 slug。只有 OAuth 和 PAT 传输会携带显示名称，stdio 不受影响。
测试与开发：可运行服务器对接某个工作区；测试、格式化和 lint 也有对应命令。测试套件完全离线运行，会针对一个替身执行每种资源的每个动作，并按真实的 plane-sdk 签名约束每次调用（详见 plane_mcp/tools/README.md）。除非将其指向正在运行的服务器，否则实况集成测试会被跳过；这些测试会向该工作区写入真实数据。仓库欢迎提交拉取请求，提交前请运行 pytest 和 ruff check；新工具应带有 plane_mcp/tools/README.md 中描述的不变量。另见 CONTRIBUTING.md 和 CODE_OF_CONDUCT.md。
从 Node.js 服务器迁移：@makeplane/plane-mcp-server（Node.js）已弃用且不再维护，本 Python 实现将其取代。迁移时用快速开始中的 stdio 配置替换原命令和参数即可。
许可证：MIT，见 LICENSE。
暂未提供的细节包括完整工具与动作参考的具体内容、自托管服务器的详细命令、OAuth 允许列表追加模式的具体写法、PQL 完整语法正文，以及各项测试命令的原文，需以仓库文档为准。
