内容
# mcp-plane
[](https://github.com/c3-oss/mcp-plane/actions/workflows/ci.yml)
[](https://github.com/c3-oss/mcp-plane/actions/workflows/release.yml)
[](LICENSE)
mcp 服务器（stdio）暴露 plane REST API 作为工具，以便 mcp 客户端可以直接驱动 plane。
## 配置
设置三个环境变量：
| 变量 | 是否必需 | 默认值 | 备注 |
|---|---|---|---|
| `PLANE_API_TOKEN` | 是 | — | 从 plane → 设置 → API 令牌获取的个人访问令牌。不接受 `changeme` 等占位符。 |
| `PLANE_WORKSPACE` | 是 | — | 工作区 slug（plane URL 中的值）。 |
| `PLANE_BASE_URL` | 是 | — | 自托管 plane 基础 URL，不带尾斜杠。 |
## 运行
已发布的 npm 包是推荐的方式 — 无需构建步骤，无需手动管理二进制文件：
```bash
PLANE_BASE_URL=... PLANE_API_TOKEN=... PLANE_WORKSPACE=... \
npx -y @c3-oss/mcp-plane
```
`@c3-oss/mcp-plane` 是一个薄的 JS 封装层，委托给与您的平台（darwin/linux × amd64/arm64）匹配的预构建 Go 二进制文件，该二进制文件通过 npm `optionalDependencies` 分发。无需 `postinstall` 下载。
或者在本地构建：
```bash
just build
PLANE_BASE_URL=... PLANE_API_TOKEN=... PLANE_WORKSPACE=... ./bin/mcp-plane
```
无论哪种方式，二进制文件都通过 stdio 以 JSON-RPC 2.0 协议与 MCP 规范通信。日志输出到 stderr；stdout 保留用于协议。
### 注册到 MCP 客户端
Claude Desktop / Claude Code (`~/.claude.json`)，通过 npx：
```json
{
"mcpServers": {
"plane": {
"command": "npx",
"args": ["-y", "@c3-oss/mcp-plane"],
"env": {
"PLANE_BASE_URL": "https://plane.example.com",
"PLANE_API_TOKEN": "...",
"PLANE_WORKSPACE": "..."
}
}
}
}
```
或指向本地构建的二进制文件：
```json
{
"mcpServers": {
"plane": {
"command": "/abs/path/to/bin/mcp-plane",
"env": {
"PLANE_BASE_URL": "https://plane.example.com",
"PLANE_API_TOKEN": "...",
"PLANE_WORKSPACE": "..."
}
}
}
}
```
## 工具
已注册 23 个工具。有关完整表格，请参见 [`docs/tools.md`](docs/tools.md)；下面是摘要：
| 分组 | 工具 |
|---|---|
| 项目 | `plane_project_list` |
| 问题 | `plane_issue_create`、`plane_issue_list`、`plane_issue_get`、`plane_issue_get_by_identifier`、`plane_issue_update`、`plane_issue_delete` |
| 状态 / 标签 | `plane_state_list`、`plane_label_list` |
| 评论 | `plane_comment_list`、`plane_comment_add`、`plane_comment_update`、`plane_comment_delete` |
| 活动 | `plane_activity_list` |
| 附件 | `plane_attachment_list`、`plane_attachment_init_upload`、`plane_attachment_complete_upload`、`plane_attachment_upload`、`plane_attachment_read` |
| 高级 | `plane_issue_transfer`、`plane_issue_workpad_upsert` |
| 健康检查 | `plane_workspace_info`、`plane_health` |
输入接受 plane 原生 ID（uuid 用于项目/问题/状态/标签，或工作区标识符，如 `PROJ-7` 用于按标识符查找）。
`plane_project_list` 返回项目 ID 和项目范围工具的标识符。
## 验证
有关端到端 stdin/stdout 探测和手动烟雾测试，请参见 [`docs/verifying.md`](docs/verifying.md)。
## 开发
通过 [devbox](https://www.jetify.com/devbox) 固定工具链；使用 `devbox shell` 进入。然后：
```bash
just build # 编译 bin/mcp-plane
just test-race # 完整的竞态检测
just lint # golangci-lint v2
just ci # PR 管道的本地镜像
just snapshot # goreleaser --snapshot（写入 dist/ 和 SBOM）
just docker-build # 构建本地 Docker 镜像
```
有关规范的项目指南，请参见 [`AGENTS.md`](AGENTS.md)。
## 许可证
在法律允许的最大范围内，[Caian Ertl][me] 已放弃对该作品的所有版权和相关或邻接权利。在 _信息自由_ 的精神下，我鼓励您 fork、修改、更改、分享或对该项目做任何您喜欢的事情！[`^C ^V`][kopimi]
[![License][cc-shield]][cc-url]
[me]: https://github.com/upsetbit
[cc-shield]: https://forthebadge.com/images/badges/cc-0.svg
[cc-url]: http://creativecommons.org/publicdomain/zero/1.0
[kopimi]: https://kopimi.com
