内容
# Planka v2.x MCP
**将 Claude, Cursor, Codex 等 MCP 客户端直接连接到您的 Planka v2.x 看板。**
为您的 AI 代理提供安全、结构化的项目、看板、卡片、任务、评论、标签和工作流访问权限，通过模型上下文协议（MCP）。
<p align="center">
<a href="https://www.npmjs.com/package/@goldpulpy/planka-v2-mcp">
<img
alt="npm version"
src="https://img.shields.io/npm/v/%40goldpulpy%2Fplanka-v2-mcp"
/>
</a>
<a href="https://www.npmjs.com/package/@goldpulpy/planka-v2-mcp">
<img
alt="npm downloads"
src="https://img.shields.io/npm/dm/%40goldpulpy%2Fplanka-v2-mcp"
/>
</a>
<a href="https://github.com/goldpulpy/planka-v2-mcp/actions/workflows/ci.yml">
<img
alt="CI"
src="https://img.shields.io/github/actions/workflow/status/goldpulpy/planka-v2-mcp/ci.yml?branch=main&label=CI"
/>
</a>
<img alt="Node.js" src="https://img.shields.io/badge/node-%3E%3D18-339933" />
<img
alt="TypeScript"
src="https://img.shields.io/badge/TypeScript-5.x-3178C6"
/>
<a href="./LICENSE">
<img
alt="License: MIT"
src="https://img.shields.io/badge/License-MIT-yellow.svg"
/>
</a>
<a href="https://docs.planka.app">
<img
alt="Planka v2.x"
src="https://img.shields.io/badge/Planka-v2.x-blueviolet"
/>
</a>
<a href="https://modelcontextprotocol.io">
<img
alt="MCP compatible"
src="https://img.shields.io/badge/MCP-compatible-2ea44f"
/>
</a>
</p>
> [!IMPORTANT]
> 专门为 **Planka v2.x** 构建。此 MCP 与 Planka v1.x 不兼容。
## 为什么选择 Planka MCP？
Planka 提供了一个优秀的 Web 界面供人类用户使用。但是，AI 代理需要结构化的项目、看板、卡片、任务、评论和工作流访问权限。
此 MCP 服务器通过模型上下文协议（MCP）公开 Planka v2 API，允许 Claude、Cursor、Codex 等 AI 代理使用自然语言与 Planka 交互。
## 支持的 Planka 版本
| Planka 版本 | 状态 |
| -------------- | ------------------- |
| 2.0.0-rc.2 | ✅ 已测试 |
| 2.1.1 | ✅ 已测试 |
| 更新的 2.x | ⚠️ 预期可工作 |
## 功能
- 完整的项目和看板管理
- 完整的卡片生命周期管理
- 任务列表和任务支持
- 评论、标签和分配
- 卡片时间跟踪
- 项目和看板摘要
- MCP 原生工具界面
- 支持主要的 MCP 客户端
- 自托管和云 Planka 支持
<details>
<summary><strong>示例对话</strong></summary>
### 项目设置
**用户**
> 创建一个名为“Website Redesign”的项目，包含“Backlog”、“In Progress”和“Done”看板。
**助手**
```text
✓ 已创建项目“Website Redesign”
✓ 已创建看板“Backlog”
✓ 已创建看板“In Progress”
✓ 已创建看板“Done”
项目设置完成。
```
### 任务创建
**用户**
> 在 Backlog 看板中创建一个名为“Implement authentication”的卡片，包含以下任务：
>
> - 设计登录流程
> - 实现 JWT 身份验证
> - 添加密码重置
> - 编写测试
**助手**
```text
✓ 已创建卡片“Implement authentication”
✓ 已创建任务列表
✓ 已添加 4 个任务
```
### 工作流自动化
**用户**
> 查找所有指派给我的过期卡片，将它们移到“Blocked”，添加解释性评论，并生成项目摘要。
**助手**
```text
✓ 找到 7 张过期卡片
✓ 将卡片移到“Blocked”
✓ 添加解释性评论
✓ 生成更新的项目摘要
```
</details>
<details>
<summary><strong>可用工具</strong></summary>
| 工具名称 | 操作 | 描述 |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `project_board_manager` | `get_projects` · `create_project` · `get_project` · `update_project` · `delete_project` · `get_boards` · `create_board` · `get_board` · `update_board` · `delete_board` · `get_board_summary` · `get_project_summary` | 项目和看板，包括聚合摘要 |
| `list_manager` | `get_all` · `create` · `get_one` · `update` · `delete` | 看板内的列表 |
| `card_manager` | `get_all` · `create` · `get_one` · `update` · `move` · `duplicate` · `delete` · `create_with_tasks` · `get_details` | 卡片，包括一键创建带有任务清单的卡片 |
| `stopwatch` | `start` · `stop` · `get` · `reset` | 卡片时间跟踪 |
| `label_manager` | `get_all` · `create` · `update` · `delete` · `add_to_card` · `remove_from_card` | 看板标签及其在卡片上的分配 |
| `task_list_manager` | `get_all` · `create` · `get_one` · `update` · `delete` | 卡片内的任务列表（Planka v2.0 实体） |
| `task_manager` | `get_all` · `create` · `batch_create` · `get_one` · `update` · `delete` · `complete_task` | 单个任务，包括批量创建 |
| `comment_manager` | `get_all` · `create` · `get_one` · `update` · `delete` | 卡片上的评论 |
| `membership_manager` | `get_all` · `create` · `get_one` · `update` · `delete` | 看板级别的成员和角色（`editor` / `viewer`） |
| `card_membership_manager` | `get_all` · `get_users` · `create` · `delete` | 通过 **ID、邮箱或用户名** 指派/移除卡片成员 |
</details>
## 快速入门
### 要求
- 运行中的 Planka v2.x 实例
- 为您的 AI 代理专门创建的 Planka 用户账户
- Node.js 18+（如果在本地运行）
> [!IMPORTANT]
> 创建 MCP 账户后，请使用该账户登录 Planka Web 界面，并接受服务条款，然后再配置或启动 MCP 服务器。这是每个新账户的必要步骤。
### 配置您的 MCP 客户端
每个 MCP 兼容的客户端都使用相同的底层命令 - 只有配置文件的位置（有时还有 JSON 包装器）有所不同。请参阅以下您特定工具的客户端配置示例。
核心配置块始终是：
```json
{
"command": "npx",
"args": ["-y", "@goldpulpy/planka-v2-mcp@latest"],
"env": {
"PLANKA_BASE_URL": "https://your-planka-instance.com",
"PLANKA_AGENT_EMAIL": "agent@yourdomain.com",
"PLANKA_AGENT_PASSWORD": "your-secure-password",
"PLANKA_IGNORE_SSL": "true"
}
}
```
<details>
<summary><strong>替代：从本地构建运行</strong></summary>
```json
{
"command": "node",
"args": ["/absolute/path/to/planka-v2-mcp/dist/index.js"],
"env": {
"PLANKA_BASE_URL": "https://your-planka-instance.com",
"PLANKA_AGENT_EMAIL": "agent@yourdomain.com",
"PLANKA_AGENT_PASSWORD": "your-secure-password",
"PLANKA_IGNORE_SSL": "true"
}
}
```
这在您自己为服务器做出贡献或需要固定、离线构建时很有用。
</details>
> [!TIP]
> 仅在受信任的本地或自托管环境中使用自签名证书时，将 `PLANKA_IGNORE_SSL` 设置为 `"true"` - 在生产环境中请勿这样做。
### 验证连接
首先请您的代理执行只读操作，例如 _“列出我的 Planka 项目。”_ 如果您收到实际的回复，则表示连接正确。
## 客户端配置示例
大多数 MCP 客户端共享相同的 `mcpServers` JSON 结构 - 只有配置文件的位置有所不同。客户端的配置块如下：
<details open>
<summary><strong>标准 <code>mcpServers</code> 客户端</strong> - Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Antigravity</summary>
<br>
```json
{
"mcpServers": {
"planka-mcp": {
"command": "npx",
"args": ["-y", "@goldpulpy/planka-v2-mcp@latest"],
"env": {
"PLANKA_BASE_URL": "https://your-planka-instance.com",
"PLANKA_AGENT_EMAIL": "agent@yourdomain.com",
"PLANKA_AGENT_PASSWORD": "your-secure-password",
"PLANKA_IGNORE_SSL": "true"
}
}
}
}
```
将此块放入相关配置文件中：
| 客户端 | 配置文件 |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Claude Desktop** | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` · Windows: `%APPDATA%\Claude\claude_desktop_config.json` |
| **Claude Code (CLI)** | `.mcp.json` 在项目根目录（或 `claude mcp add`, 参见下文） |
| **Cursor** | `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（项目） |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
| **Cline** (VS Code) | `cline_mcp_settings.json`, via **Cline → MCP Servers → Configure MCP Servers** （添加 `"disabled": false, "autoApprove": []` 到服务器条目） |
| **Antigravity** | 通过 **Settings → MCP Servers → Add Server**，或直接在其配置文件中 |
> [!NOTE]
> Claude Code 还支持使用一行命令添加服务器，而不是手动编辑 JSON：
>
> ```bash
> claude mcp add planka-mcp \
> --env PLANKA_BASE_URL=https://your-planka-instance.com \
> --env PLANKA_AGENT_EMAIL=agent@yourdomain.com \
> --env PLANKA_AGENT_PASSWORD=your-secure-password \
> --env PLANKA_IGNORE_SSL=true \
> -- npx -y @goldpulpy/planka-v2-mcp@latest
> ```
重启客户端后生效。
</details>
<details>
<summary><strong>Codex CLI</strong></summary>
<br>
编辑 `~/.codex/config.toml`:
```toml
[mcp_servers.planka-mcp]
command = "npx"
args = ["-y", "@goldpulpy/planka-v2-mcp@latest"]
[mcp_servers.planka-mcp.env]
PLANKA_BASE_URL = "https://your-planka-instance.com"
PLANKA_AGENT_EMAIL = "agent@yourdomain.com"
PLANKA_AGENT_PASSWORD = "your-secure-password"
PLANKA_IGNORE_SSL = "true"
```
或使用一行命令添加：
```bash
codex mcp add planka-mcp -- npx -y @goldpulpy/planka-v2-mcp@latest
```
然后在生成的 `[mcp_servers.planka-mcp.env]` 块中设置 `PLANKA_*` 变量。
</details>
<details>
<summary><strong>Continue (VS Code / JetBrains 扩展)</strong></summary>
<br>
添加到 `~/.continue/config.yaml`:
```yaml
mcpServers:
- name: planka-mcp
command: npx
args:
- -y
- "@goldpulpy/planka-v2-mcp@latest"
env:
PLANKA_BASE_URL: https://your-planka-instance.com
PLANKA_AGENT_EMAIL: agent@yourdomain.com
PLANKA_AGENT_PASSWORD: your-secure-password
PLANKA_IGNORE_SSL: "true"
```
</details>
<details>
<summary><strong>Zed</strong></summary>
<br>
编辑 `~/.config/zed/settings.json`（macOS/Linux）或 `%APPDATA%\Zed\settings.json`（Windows），或通过 **Cmd+Shift+P → "zed: open settings"** 打开：
```json
{
"context_servers": {
"planka-mcp": {
"source": "custom",
"command": "npx",
"args": ["-y", "@goldpulpy/planka-v2-mcp@latest"],
"env": {
"PLANKA_BASE_URL": "https://your-planka-instance.com",
"PLANKA_AGENT_EMAIL": "agent@yourdomain.com",
"PLANKA_AGENT_PASSWORD": "your-secure-password",
"PLANKA_IGNORE_SSL": "true"
}
}
}
}
```
`"source": "custom"` 对于手动添加的服务器是必需的（相对于通过 Zed 扩展安装的服务器）。Zed 在保存后会自动重新加载服务器 - 无需重启编辑器。
</details>
<details>
<summary><strong>任何其他 MCP 兼容客户端</strong></summary>
<br>
服务器是一个标准的 stdio MCP 服务器 - 任何支持 `command` / `args` / `env` 结构的客户端都可以使用。将客户端指向：
```bash
npx -y @goldpulpy/planka-v2-mcp@latest
```
并设置上面所示的四个 `PLANKA_*` 环境变量。
</details>
## 环境变量
| 变量 | 必需 | 默认值 | 描述 |
| ----------------------- | :------: | :-----: | ---------------------------------------------------- |
| `PLANKA_BASE_URL` | ✅ | - | 您的 Planka 实例的全 URL |
| `PLANKA_AGENT_EMAIL` | ✅ | - | 专用代理用户的登录邮箱 |
| `PLANKA_AGENT_PASSWORD` | ✅ | - | 代理用户的密码 |
| `PLANKA_IGNORE_SSL` | ❌ | `false` | 跳过 SSL 验证 - 仅限自签名/本地证书 |
## 安全
- 身份验证使用专用 Planka 用户账户进行。
- 凭证仅通过环境变量提供。
- MCP 服务器不会在运行进程之外持久化看板数据。
- 默认启用 SSL 证书验证。
- `PLANKA_IGNORE_SSL=true` 仅应在受信任的本地或自托管环境中使用。
## 故障排除
<details>
<summary><strong>客户端无法看到任何工具 / 连接失败静默</strong></summary>
<br>
- 确认 `PLANKA_BASE_URL` 没有尾部斜杠，并且可以从运行 MCP 服务器的机器访问（不仅仅是您的浏览器）。
- 检查代理用户可以使用确切的凭证通过 Planka 的正常 Web 界面登录并接受服务条款。
</details>
<details>
<summary><strong>SSL / 证书错误</strong></summary>
<br>
- 如果您的实例使用自签名证书，请设置 `"PLANKA_IGNORE_SSL": "true"`。避免在生产环境中使用此选项 - 而是使用有效的证书。
</details>
<details>
<summary><strong>创建的卡片没有显示清单/子任务</strong></summary>
<br>
- 确保卡片类型为 `"project"`（默认）。创建为 `"story"` 类型的卡片不以相同的方式公开任务列表。
</details>
## 开发
```bash
# 安装依赖
npm install
# 配置环境变量
cp .env.example .env
# 启动附带的 Planka 开发实例
npm run planka:up
# 构建项目
npm run build
# 运行 @modelcontextprotocol/inspector
npm run inspector
```
开发实例需要 Docker Compose，并且可在
`http://localhost:3000` 访问（登录：`admin@example.com` / `admin`). 更新 `.env` 并使用可访问的 Planka v2
实例和有效的 `PLANKA_BASE_URL`、`PLANKA_AGENT_EMAIL` 和 `PLANKA_AGENT_PASSWORD` 值
在运行之前。 与任何新创建的 MCP 账户一样，请通过浏览器登录并接受服务条款，然后使用账户与
MCP 服务器。停止实例并保留其数据 `npm run planka:down`，或停止并删除其卷 `npm run planka:clear`。
### 种子演示板
仅限开发环境的 seed 命令会创建代表性板以创建本地测试和演示文稿。安装项目依赖并使用可访问的 Planka v2
实例以及有效的 `PLANKA_BASE_URL`、`PLANKA_AGENT_EMAIL` 和 `PLANKA_AGENT_PASSWORD` 值
在运行之前。
```bash
# 重用或创建私有“Demo Project”，然后创建“Demo Board”
npm run seed
# 种子现有项目
npm run seed -- --project-id <project-id>
# 选择不同的板名
npm run seed -- --project-id <project-id> --board-name "My Demo Board"
# 显示所有选项
npm run seed -- --help
```
该板包括来自默认工作流列表的卡片、描述、相对到期日期、
Planka 标签用作标签，任务列表，完成和未完成的任务以及评论。命令
在成功时打印项目 ID、板 ID、板名和资源计数。
该种子源及其单独编译的 `.seed-dist/` 输出仅用于开发，不
包含在 MCP 服务器构建或发布的软件包中。
## 贡献
欢迎贡献。详见 [CONTRIBUTING.md](./CONTRIBUTING.md) 获取详细信息。
## 致谢
本项目从 [Navya-Tecnologia/planka-v2-mcp](https://github.com/Navya-Tecnologia/planka-v2-mcp) 分叉而来，后者建立在 [bradrisse/kanban-mcp](https://github.com/bradrisse/kanban-mcp) 的基础上。感谢 [@virapa](https://github.com/virapa) 和 [@bradrisse](https://github.com/bradrisse) 提供此代码库的基础。
## 许可证
遵循 MIT 许可证。详见 [LICENSE](./LICENSE) 获取详细信息。
<p align="center"><em>该项目仅专注于 MCP 接口。对于 Planka 服务器设置本身，请参阅 <a href="https://docs.planka.app">官方 Planka 文档</a>。</em></p>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器