planka

PLANKA MCP 服务

适用于 PLANKA 看板的模型上下文协议（MCP）服务，专为 Claude 和其他 AI Agent 打造。

功能

• 全面支持 PLANKA 2.0 API
• 使用 Zod 验证，确保类型安全
• 针对 Agent 工作流进行优化（组合操作、合理的默认值）
• 提供 13 个工具，涵盖卡片、任务、标签、评论和列表

安装

npm install @gogogadgetbytes/planka-mcp

也可以直接运行：

npx @gogogadgetbytes/planka-mcp

配置

环境变量

变量	必需	说明
PLANKA_BASE_URL	是	PLANKA 服务的 URL
PLANKA_AGENT_EMAIL	是	Agent 用户邮箱
PLANKA_AGENT_PASSWORD	是	Agent 用户密码

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "planka": {
      "command": "npx",
      "args": ["@gogogadgetbytes/planka-mcp"],
      "env": {
        "PLANKA_BASE_URL": "https://planka.example.com",
        "PLANKA_AGENT_EMAIL": "[email protected]",
        "PLANKA_AGENT_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code

添加到 ~/.claude.json：

{
  "mcpServers": {
    "planka": {
      "command": "npx",
      "args": ["@gogogadgetbytes/planka-mcp"],
      "env": {
        "PLANKA_BASE_URL": "https://planka.example.com",
        "PLANKA_AGENT_EMAIL": "[email protected]",
        "PLANKA_AGENT_PASSWORD": "your-password"
      }
    }
  }
}

可用工具

导航

工具	说明
planka_get_structure	获取项目、看板和列表的层级结构
planka_get_board	获取包含所有卡片、列表和标签的看板

卡片

工具	说明
planka_create_card	创建卡片（可选包含任务）
planka_update_card	更新卡片属性
planka_move_card	将卡片移动到其他列表或位置
planka_get_card	获取卡片详情，包括任务和评论
planka_delete_card	删除卡片

任务

工具	说明
planka_create_tasks	向卡片添加任务（检查清单项）
planka_update_task	更新任务名称或完成状态
planka_delete_task	删除任务

标签

工具	说明
planka_manage_labels	创建、更新或删除看板标签
planka_set_card_labels	为卡片添加或移除标签

评论

工具	说明
planka_add_comment	向卡片添加评论
planka_get_comments	获取卡片的所有评论

列表

工具	说明
planka_manage_lists	创建、更新或删除列表

使用示例

获取看板结构

Use planka_get_structure to see all projects and boards

创建包含任务的卡片

Use planka_create_card with:
- listId: "abc123"
- name: "Implement feature X"
- tasks: ["Research", "Design", "Implement", "Test"]

在工作流中移动卡片

Use planka_move_card to move card from "To Do" to "In Progress"

PLANKA 2.0 兼容性

此服务专为 PLANKA 2.0 设计，并处理了与 1.x 版本的 API 差异：

• 创建卡片时包含必需的 type 字段
• 标签端点使用 /card-labels 路径
• 妥善处理可选字段

开发

# Clone
git clone https://github.com/gogogadgetbytes/planka-mcp.git
cd planka-mcp

# Install
npm install

# Build
npm run build

# Test
npm test

许可证

MIT

链接

• PLANKA - 看板
• MCP SDK - 模型上下文协议
• 设计文档 - 技术设计详情