Planka 2.x的看板MCP

Planka 2.0.0-rc.4及更高版本的模型上下文协议（MCP）服务器

![License: MIT](https://opensource.org/licenses/MIT)

📚 AI助手示例和提示 -GitHub Copilot、Claude和Gemini的现成示例

⚠️ 版本兼容性

此MCP服务器是专门为 Planka 2.0.0-rc.4及更高版本.

Planka版本	兼容的MCP存储库
2.0.0-rc.4+	这个仓库 (apkuki/kanban-mcp-planka-v2)
1.x	bradrisse/看板mcp （原件）

为什么要单独回购？ Planka 2.0引入了与1.x版本不兼容的API重大更改。该fork没有破坏现有用户的原始MCP，而是保持了与Planka 2.x的兼容性。

______________________________________________________________________

🎯 特性

核心功能

✅ 项目和董事会 -完整的CRUD操作
✅ 列表 -创建、读取、更新、删除板列表
✅ 卡片 -使用所有元数据完成卡片管理
✅ 卡片复制 -克隆卡及其所有属性
✅ 任务列表和任务 -使用复选框项目创建检查表
✅ 评论 -添加、更新、删除卡片评论
✅ 标签 -具有25种颜色选项的完整标签管理
✅ 董事会成员 -管理用户对板的访问权限
✅ 秒表 -卡片上的时间追踪

增强功能

🆕 批量操作 -在一次通话中创建多个项目
🆕 带任务的任务列表 -在一次操作中创建项目清单
🆕 董事会摘要 -获取全面的董事会概述
🆕 卡详细信息 -获取完整的卡片信息及相关数据

______________________________________________________________________

🚀 安装

先决条件

Node.js 18+或Bun
Docker（如果在本地运行Planka）
Planka 2.0.0-rc.4+实例（现有或新的）

______________________________________________________________________

选项A：连接到现有Planka实例

如果您已经在运行Planka，请使用此功能 （例如在服务器或不同的机器上）。

克隆和构建：

   git clone https://github.com/apkuki/kanban-mcp-planka-v2.git
   cd kanban-mcp-planka-v2
   npm install
   npm run build

配置您的MCP客户端：

对于 克劳德桌面 (claude_desktop_config.json):

   {
     "mcpServers": {
       "kanban-planka-v2": {
         "command": "node",
         "args": ["/absolute/path/to/kanban-mcp-planka-v2/dist/index.js"],
         "env": {
           "PLANKA_BASE_URL": "http://localhost:3333",
           "PLANKA_AGENT_KEY": "your-api-key-from-planka"
         }
       }
     }
   }

替代方案：电子邮件/密码验证:

   {
     "mcpServers": {
       "kanban-planka-v2": {
         "command": "node",
         "args": ["/absolute/path/to/kanban-mcp-planka-v2/dist/index.js"],
         "env": {
           "PLANKA_BASE_URL": "http://localhost:3333",
           "PLANKA_AGENT_EMAIL": "your-email@example.com",
           "PLANKA_AGENT_PASSWORD": "your-password"
         }
       }
     }
   }

替换值：

- 路径：您通往的实际路径 dist/index.js 文件 - 网址： http://localhost:3333 对于本地Planka或您的服务器URL（例如。， https://planka.yourcompany.com) - API密钥：在Planka用户设置中生成→ API密钥（建议用于v2.0.1+版本） - OR电子邮件/密码：现有Planka用户的凭据（传统方法）

对于光标 (.cursor/mcp.json 或全局设置）：

   {
     "mcpServers": {
       "kanban-planka-v2": {
         "command": "node",
         "args": ["/absolute/path/to/kanban-mcp-planka-v2/dist/index.js"],
         "env": {
           "PLANKA_BASE_URL": "http://localhost:3333",
           "PLANKA_AGENT_KEY": "your-api-key-from-planka"
         }
       }
     }
   }

注：在Windows上，使用正斜杠 / 在路上，或者像这样避开睫毛 C:\\path\\to\\file.js

对于 GitHub Copilot命令行界面 (~/.mcp/mcp-config.json):

   {
     "mcpServers": {
       "kanban-planka-v2": {
         "command": "node",
         "args": ["/absolute/path/to/kanban-mcp-planka-v2/dist/index.js"],
         "env": {
           "PLANKA_BASE_URL": "http://localhost:3333",
           "PLANKA_AGENT_KEY": "your-api-key-from-planka"
         }
       }
     }
   }

重新启动MCP客户端 加载服务器。

______________________________________________________________________

选项B：一起运行Planka+MCP（Docker）

如果您想在本地运行Planka，请使用此选项 在Docker中，MCP服务器旁边。

克隆存储库：

   git clone https://github.com/apkuki/kanban-mcp-planka-v2.git
   cd kanban-mcp-planka-v2
   npm install

配置环境变量：

编辑 .env 项目根目录中的文件：

   # Planka Configuration
   PLANKA_PORT=3333
   BASE_URL=http://localhost:3333
   SECRET_KEY=your-secret-key-here

   # Admin User (created on first run)
   PLANKA_ADMIN_EMAIL=admin@example.com
   PLANKA_ADMIN_PASSWORD=your-secure-password
   PLANKA_ADMIN_NAME=Admin User
   PLANKA_ADMIN_USERNAME=admin

   # PostgreSQL Configuration
   POSTGRES_USER=postgres
   POSTGRES_PASSWORD=postgres
   POSTGRES_DB=planka

   # MCP-Kanban Configuration
   MCP_KANBAN_PORT=3008
   PLANKA_BASE_URL=http://planka:${PLANKA_PORT}
   PLANKA_AGENT_EMAIL=${PLANKA_ADMIN_EMAIL}
   PLANKA_AGENT_PASSWORD=${PLANKA_ADMIN_PASSWORD}

重要变量：

- PLANKA_ADMIN_EMAIL -您的Planka管理员用户的电子邮件 - PLANKA_ADMIN_PASSWORD -管理员用户的密码 - SECRET_KEY -为了安全起见，将其更改为随机字符串 - PLANKA_BASE_URL -Planka可访问的URL

构建MCP服务器：

   npm run build

在Docker中启动Planka：

   npm run up
   # or
   docker compose up -d

访问Planka：

- 打开http://localhost:3333在浏览器中 - 使用您在中设置的凭据登录 .env

配置您的MCP客户端：

使用与选项A相同的配置，但具有：

   "env": {
     "PLANKA_BASE_URL": "http://localhost:3333",
     "PLANKA_AGENT_EMAIL": "admin@example.com",
     "PLANKA_AGENT_PASSWORD": "your-secure-password"
   }

重新启动MCP客户端。

______________________________________________________________________

🔑 身份验证说明

身份验证方法：

Planka 2.0.1+支持两种身份验证方法：

API密钥验证（建议用于2.0.1+版本）:

- 板材_基材_钢筋：Planka实例的基本URL（没有尾随斜线） - PLANKA_AGENT_KEY：Planka用户设置中的API密钥 - 更安全、更简单的设置 - 在Planka:用户设置中生成API密钥→ API密钥

电子邮件/密码验证（传统）:

- 板材_基材_钢筋：Planka实例的基本URL（没有尾随斜线） - Planka代理电子邮件：Planka用户的电子邮件（必须存在于Planka中） - PLANKA_AGENT_PASSWORD：该用户的密码 - MCP服务器以该用户身份登录，并代表他们执行所有操作

注：如果两者都已配置，则API密钥身份验证优先。

______________________________________________________________________

📚 使用示例

任务清单（检查表）

// Create a checklist with tasks in one operation
kanban-mcp_kanban_task_manager({
  action: "create_tasklist_with_tasks",
  cardId: "card_id_here",
  name: "Testing Checklist",
  tasks: [
    { name: "□ Run unit tests" },
    { name: "□ Run integration tests" },
    { name: "□ Update documentation" }
  ]
})

// Get all task lists for a card
kanban-mcp_kanban_task_manager({
  action: "get_all",
  cardId: "card_id_here"
})

// Create a comment
kanban-mcp_kanban_comment_manager({
  action: "create",
  cardId: "card_id_here",
  text: "Implementation complete, ready for review"
})

// Get all comments
kanban-mcp_kanban_comment_manager({
  action: "get_all",
  cardId: "card_id_here"
})

卡片

// Create a card
kanban-mcp_kanban_card_manager({
  action: "create",
  listId: "list_id_here",
  name: "New Feature",
  description: "Implement new feature X"
})

// Move a card within the same board
kanban-mcp_kanban_card_manager({
  action: "move",
  id: "card_id_here",
  listId: "target_list_id",
  position: 0  // Optional: defaults to end of list (65535)
})

// Move a card to a different board
kanban-mcp_kanban_card_manager({
  action: "move",
  id: "card_id_here",
  listId: "target_list_id",
  boardId: "target_board_id",  // REQUIRED when moving between boards
  position: 0  // Optional
})

// Move a card to a different project
kanban-mcp_kanban_card_manager({
  action: "move",
  id: "card_id_here",
  listId: "target_list_id",
  boardId: "target_board_id",  // REQUIRED
  projectId: "target_project_id",  // REQUIRED when moving between projects
  position: 0  // Optional
})

// Get card details with related data
kanban-mcp_kanban_card_manager({
  action: "get_details",
  cardId: "card_id_here"
})

⚠️ 重要提示：在板和列表之间移动卡片

移动卡片时，所需参数取决于移动范围：

移动范围	必需参数	可选
同一董事会内	`id`, `listId`	`position`
木板之间	`id`, `listId`, `boardId`	`position`
项目之间	`id`, `listId`, `boardId`, `projectId`	`position`

要避免的常见错误：

❌ 遗忘 boardId 在板之间移动卡片时
❌ 遗忘 projectId 在项目之间移动卡片时
❌ 假设 position 是必需的（默认为列表末尾）

🤖 人工智能辅助工作流示例

此MCP服务器可与AI助手无缝集成，如 GitHub Copilot命令行界面 或 克劳德桌面 通过Planka管理您的开发工作流程。

双板系统：待办事项+工作日志

一种经过验证的工作流程模式，使用两个板来组织从计划到完成的问题：

📋 BACKLOG BOARD                        📊 WORKLOG BOARD
├── Architecture (ARCH-xxx)            ├── Planned (ready to build)
├── Security (SEC-xxx)                 ├── In Progress (actively working)
├── Performance (PERF-xxx)             ├── Testing (awaiting verification)
└── Feature (FEAT-xxx)                 └── Completed (done)

标签：

优先： Critical （红色）| High （橙色）| Normal （黄色）
状态由板位置跟踪 （卡片在哪个列表中）

______________________________________________________________________

AI工作流说明示例

将此复制到您的AI助手的自定义说明中（例如，GitHub Copilot .github/copilot-instructions.md 或克劳德的项目说明）：

# Kanban Workflow with MCP

## Board Structure
- **Backlog Board** (ID: `your_backlog_board_id`)
  - Lists: Architecture, Security, Performance, Feature
  - Issues with priority labels only (Critical/High/Normal)
  
- **Worklog Board** (ID: `your_worklog_board_id`)
  - Lists: Planned, In Progress, Testing, Completed
  - Issues with priority labels (status = which list they're in)

## Workflow Phases

### 1️⃣ Creating New Issues
When discovering work that needs to be done:
1. Create card in appropriate Backlog board list (Architecture/Security/Performance/Feature)
2. Add priority label: Critical/High/Normal
3. Write brief description of the issue
4. Get card URL and track in your project documentation

**Example:**

// Create security issue in Backlog kanban-mcp_kanban_card_manager({ action: "create", listId: "security_list_id", name: "SEC-001: Missing rate limiting on login endpoint", description: "Login endpoint vulnerable to brute force attacks" })

// Add priority label kanban-mcp_kanban_label_manager({ action: "add_to_card", cardId: "new_card_id", labelId: "critical_label_id" })


### 2.️⃣ 规划阶段

当用户说“计划问题XYZ”时：

1. **读卡新鲜** 来自Planka（用户可能已编辑）
1. 分析代码库以了解范围
1. **编写实施计划** 卡描述：

## Implementation Plan

### Summary Brief approach overview

### Steps 1. Step one with details 2. Step two with details

### Files to Modify - path/to/file.ts - what changes

### Testing Notes - How to verify

1. **移动卡片** 到工作日志板→ “计划”列表
1. 添加注释：“计划创建于｛date｝”

**例子：**

// Update card description with plan kanban-mcp_kanban_card_manager({ action: "update", id: "card_id", description: "## Implementation Plan\n\n### Summary\n..." })

// Move to Planned list kanban-mcp_kanban_card_manager({ action: "move", id: "card_id", listId: "planned_list_id", boardId: "worklog_board_id" })

// Add comment kanban-mcp_kanban_comment_manager({ action: "create", cardId: "card_id", text: "Plan created on 2026-01-30" })


### 3.️⃣ 实施阶段

当用户说“构建问题XYZ”时：

1. **先同步** -阅读来自Planka的新卡片
1. 移至“进行中”列表
1. 按计划实施
1. 在工作时添加进度注释
1. 当完成时， **移至“测试”列表**
1. **创建测试任务列表** 带有验证步骤

**例子：**

// Move to In Progress kanban-mcp_kanban_card_manager({ action: "move", id: "card_id", listId: "in_progress_list_id" })

// Add progress comment kanban-mcp_kanban_comment_manager({ action: "create", cardId: "card_id", text: "✅ Phase 1 complete: Database schema updated" })

// When implementation done, move to Testing kanban-mcp_kanban_card_manager({ action: "move", id: "card_id", listId: "testing_list_id" })

// CRITICAL: Add testing checklist kanban-mcp_kanban_task_manager({ action: "create_tasklist_with_tasks", cardId: "card_id", name: "Testing", tasks: [ { name: "Verify feature works as expected" }, { name: "Run npm run build (confirm success)" }, { name: "Run npm run test (confirm passing)" }, { name: "Manual testing of edge cases" }, { name: "Verify no regressions" }, { name: "Update documentation if needed" } ] })


### 4.️⃣ 完成阶段

用户完成测试后：

1. 用户在Planka中检查所有测试任务
1. 用户将卡片移至“已完成”列表
1. 更新项目文档，注明完成日期

______________________________________________________________________

## 关键规则

### 工作前始终同步

**在开始对卡片进行任何操作之前，务必：**

- 从Planka读取新卡（可能已编辑）
- 检查当前板位置（它在哪个列表中）
- 阅读所有评论以获取更新

### 两级任务层次结构

- **任务清单** =容器（例如“测试清单”）
- **任务** =单个复选框项（例如“☐运行测试”）

使用 `create_tasklist_with_tasks` 创建适当的层次结构。

### 测试检查表是强制性的

转到测试列表时，始终创建一个包含验证步骤的“测试”任务列表。

### 进度评论

在完成提高透明度的主要步骤时，在卡片上添加注释。

Real-World Example

Here's how an AI assistant would handle the complete lifecycle:


用户：“为丢失率限制创建新的安全问题”
AI: → 在待办事项列表中创建卡片→ 安全列表
→ 添加“关键”标签
→ 返回卡片URL

用户：“SEC-015计划”
AI: → 从Planka读取卡片
→ 分析代码库
→ 将实施计划写入卡片描述
→ 移动到工作日志→ 计划的
→ 添加注释：“已创建计划”

用户：“构建SEC-015”
AI: → 读取新卡（检查更新）
→ 移动到工作日志→ 进行中
→ 实施速率限制
→ 为每个阶段添加注释
→ 移动到工作日志→ 测试
→ 创建包含6个验证任务的测试任务列表

用户：\[在Planka中完成测试任务\]
→ 选中所有复选框
→ 移动到已完成列表
→ AI更新项目文档并注明完成日期

Benefits

✅ Transparent Progress - All stakeholders see real-time status in Planka ✅ AI-Readable Context - AI reads cards to understand current state ✅ Async Collaboration - Team can edit cards, AI syncs before working ✅ Audit Trail - Comments and task lists document the journey ✅ Testing Accountability - Explicit checklist before marking complete

🔧 Available Tools

Tool	Description
`mcp_kanban_project_board_manager`	Manage projects and boards
`mcp_kanban_list_manager`	Manage board lists
`mcp_kanban_card_manager`	Manage cards
`mcp_kanban_task_manager`	Manage task lists and tasks
`mcp_kanban_label_manager`	Manage labels
`mcp_kanban_comment_manager`	Manage card comments
`mcp_kanban_membership_manager`	Manage board memberships
`mcp_kanban_stopwatch`	Track time on cards

📝 What's New in This Version?

Planka 2.0 API Compatibility (2026-01-30)

Fixed Issues:

✅ Updated task lists endpoints (/api/cards/:cardId/task-lists)
✅ Added support for individual tasks within task lists (/api/task-lists/:taskListId/tasks)
✅ Fixed comments endpoints (/api/cards/:cardId/comments instead of /comment-actions)
✅ All API endpoints verified against Planka 2.0.0-rc.4 routes

New Features:

🆕 create_tasklist_with_tasks - Create checklist with items in one call
🆕 Individual task management functions
🆕 Simplified comment operations
🆕 Comprehensive documentation

Breaking Changes from Original:

Task list creation now correctly uses /task-lists endpoint
Comments require cardId for retrieval
All endpoints updated to match Planka 2.0 API structure

🏗️ Architecture

Planka 2.0 Data Model


项目
└── Board
├── List
│   └── Card
│       ├── 任务清单（检查表）
│       │   └── 任务（复选框项）
│       ├── 评论
│       ├── Label
│       ├── 附件
│       └── 卡会员资格
├── Label
└── 董事会成员

Key Concepts

Task Lists vs Tasks:

Task List = A checklist on a card (e.g., "Testing Checklist")
Task = An individual checkbox item within a task list (e.g., "✓ Run tests")

Comments vs Actions:

Comments = User-created comments on cards
Actions = Activity log (includes comments + system events)

🧪 Development

Running Tests

npm test

建筑

npm run build

发展模式

npm run dev

______________________________________________________________________

🐛 故障排除

“找不到资源”错误

确保您的Planka实例是2.0.0-rc.4或更高版本
验证 PLANKA_AGENT_EMAIL 和 PLANKA_AGENT_PASSWORD 是正确的
检查用户是否存在于Planka中并且可以登录
检查一下 PLANKA_BASE_URL 没有尾随斜线

任务列表不起作用

这是Planka 2.0功能，在Planka 1.x上不起作用
确保您使用的是正确的卡号

连接错误

验证 PLANKA_BASE_URL 可从MCP服务器运行的位置访问
如果Planka打开 localhost MCP在Docker中，使用 http://host.docker.internal:3333
如果连接到远程Planka实例，请检查防火墙设置

身份验证失败

仔细检查电子邮件和密码是否与有效的Planka用户匹配
尝试使用相同的凭据登录Planka web界面
检查Planka日志中的身份验证错误

______________________________________________________________________

📋 API端点参考

Planka 2.0.0-rc.4使用的端点

# Projects & Boards
GET    /api/projects
POST   /api/projects/:projectId/boards
GET    /api/boards/:id

# Lists & Cards
POST   /api/boards/:boardId/lists
POST   /api/lists/:listId/cards
GET    /api/cards/:id

# Task Lists & Tasks
POST   /api/cards/:cardId/task-lists
POST   /api/task-lists/:taskListId/tasks
PATCH  /api/task-lists/:id
PATCH  /api/tasks/:id

# Comments
GET    /api/cards/:cardId/comments
POST   /api/cards/:cardId/comments
PATCH  /api/comments/:id

# Labels
POST   /api/boards/:boardId/labels
POST   /api/cards/:cardId/card-labels
DELETE /api/cards/:cardId/card-labels/labelId::labelId

# Memberships
POST   /api/boards/:boardId/board-memberships
PATCH  /api/board-memberships/:id

API Planka官方文件： https://plankanban.github.io/planka/swagger-ui/

______________________________________________________________________

🤝 贡献

欢迎投稿！拜托：

分叉此存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

指南

确保所有端点都匹配Planka 2.0+API
为新功能添加测试
更新文档
遵循现有代码样式

______________________________________________________________________

📜 许可证

MIT许可证-请参阅许可证详细信息文件

______________________________________________________________________

🙏 学分

原始MCP服务器： bradrisse/看板mcp
Planka项目： 木板
Planka 2.0兼容性： 更新者 @apkuki

______________________________________________________________________

📞 支持

问题：
AI助手示例： 请参阅AI_ASSISTANT_示例.md 用于即用型提示和工作流
普兰卡不和： 加入社区

______________________________________________________________________

🗺️ 路线图

已完成但功能列表中缺少

\[x\] 卡片复制 -已通过实施 duplicate 行动

进行中/部分执行

\[ \] 附件支持 -架构存在，需要操作（上传、下载、删除）

计划的功能

\[ \] 自定义字段支持 -使用用户定义的字段扩展卡
\[ \] 通知管理 -订阅和管理Planka通知
\[ \] 卡会员资格 -将用户分配到特定卡（架构存在： PlankaCardMembershipSchema)
\[ \] 项目成员资格 -管理项目级用户访问权限（架构存在： PlankaProjectMembershipSchema)

技术改进

\[ \] 改进错误处理和重试 -更好地应对网络问题
\[ \] 为API调用添加速率限制 -防止压倒性的Planka实例
\[ \] 添加缓存层以提高性能 -缓存频繁访问的数据
\[ \] 实现分页助手 -更容易处理大型结果集

锦上添花

\[ \] 批量操作 -移动多张卡片，批量分配标签
\[ \] 卡片模板 -带有检查表的预定义卡片结构
\[ \] 板克隆 -复制包含所有内容的整个板

______________________________________________________________________

由...制作❤️ 为普兰卡社区

Kanban MCP Planka V2

快速接入

详细介绍

Planka 2.x的看板MCP

⚠️ 版本兼容性

🎯 特性

核心功能

增强功能

🚀 安装

先决条件

选项A：连接到现有Planka实例

选项B：一起运行Planka+MCP（Docker）

🔑 身份验证说明

📚 使用示例

任务清单（检查表）

评论

卡片

⚠️ 重要提示：在板和列表之间移动卡片

标签

🤖 人工智能辅助工作流示例

双板系统：待办事项+工作日志

AI工作流说明示例

Real-World Example

Benefits

🔧 Available Tools

📝 What's New in This Version?

Planka 2.0 API Compatibility (2026-01-30)

🏗️ Architecture

Planka 2.0 Data Model

Key Concepts

🧪 Development

Running Tests

建筑

发展模式

🐛 故障排除

“找不到资源”错误

任务列表不起作用

连接错误

身份验证失败

📋 API端点参考

Planka 2.0.0-rc.4使用的端点

🤝 贡献

指南

📜 许可证

🙏 学分

📞 支持

🗺️ 路线图

已完成但功能列表中缺少

进行中/部分执行

计划的功能

技术改进

锦上添花

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP