planka-mcp

通过 15 个 MCP 工具，从 Claude Code 控制 Planka 2.x 看板。 写入操作会被重新读取并验证，因此报告的成功与看板实际状态一致。 一个可选工作流可将该看板转化为代理工作的持久记忆。

Leer en español

You talk to Claude Code
          │
          ▼
  planka-mcp (stdio) ─── HTTPS + JSON ───▶ Planka 2.x
          │                                  │
          └──── reads the result back ◀──────┘

[!WARNING] 旧的 @gogogadgetbytes/planka-mcp 包可能在 Planka 2.x 上报告成功，但实际上 什么都没做。在替换现有安装之前，请先阅读四个静默失败陷阱。

刚接触 MCP？请先阅读本节

MCP 是一种标准，它允许 Claude Code 调用由另一个程序提供的工具。 本仓库运行一个本地小程序，将这些工具调用转换为 Planka API 请求。 它需要 Planka 凭据，因为它以专用 Planka 用户的身份运行，而不是以 Claude 本身的身份。 凭据保留在您的机器上，绝不会写入项目级的 .mcp.json 文件。 Claude Code 在会话启动时加载 MCP 服务器，因此在设置或配置更改后请重启它。

Related MCP server: Planka MCP Server

要求

• Node.js 18 或更高版本以及 npm

• 一个可访问的 Planka 2.x 实例

• 一个可以看到目标项目和看板的专用 Planka 用户

• 已安装并可作为 claude 使用的 Claude Code

• 仅当设置需要创建看板时，才需要项目管理员角色

支持 Linux 和 macOS。不需要 Bun 运行时。

5 分钟安装

克隆仓库并运行引导式安装程序：

git clone https://github.com/omnicoreos/planka-mcp.git
cd planka-mcp
./scripts/setup.sh

设置过程会询问 Planka URL、代理邮箱或用户名以及密码。它会在写入配置之前 验证这些凭据，让您选择或创建看板，然后运行一次真实的创建/标签/评论/删除冒烟测试。

它提供两种 Claude Code 配置：

在两种情况下，设置都会将凭据存储在 Git 之外的 ~/.config/planka-mcp/config.json 中，权限为 0600，并创建私有启动器 ~/.local/bin/planka-mcp。生成的团队配置不包含密码：

{
  "mcpServers": {
    "planka": {
      "type": "stdio",
      "command": "${HOME}/.local/bin/planka-mcp",
      "args": []
    }
  }
}

安装程序可以安全地重新运行。它会更新 planka 条目，复用现有的 工作流列表和标签，并删除其临时冒烟测试卡片。

验证是否正常工作

首先，检查 Claude Code 的配置：

claude mcp list
claude mcp get planka

然后完全重启 Claude Code。如果您选择了 .mcp.json，请在该 项目中打开 Claude Code，并在提示时批准项目级服务器。

向 Claude Code 提问：

Show me my Planka projects and boards. In the Pending list, create a card named
"MCP is working" with the description "Created from Claude Code", then read it back.

如果 Claude 看不到这些工具，请先重启，然后按照 故障排除 进行操作。

15 个工具

ID 是字符串。从 planka_get_structure 开始，然后使用 Planka 返回的 ID；不要猜测它们。

每个工具的每个输入字段和完整负载都位于 工具参考 中。

可选代理工作流

MCP 服务器可以独立工作。可选方法解决的是另一个问题： 在代理会话之间保留工作存在的原因、发生的变化以及仍然成立的事实。

分层采用：

1. 仅使用 MCP 工具。

2. 添加看板状态、卡片模板和人工握手。

3. 为每张卡片添加一个工作树，由主管协调工作进程。

从一个能跨越会话存活的看板开始。 看板模板、可复制的 Claude Code 技能 以及可选的 工作树辅助工具 都是独立的组件。

故障排除

• 症状、原因和精确修复方法

• 为什么 Planka 2.x 会让旧版 MCP 服务器静默失败

• 完整的工具负载

报告错误时，请包含 Planka 版本、Node 版本、工具名称 和错误文本。切勿粘贴凭据或访问令牌。

致谢与许可证

这是 gogogadgetbytes/planka-mcp 的 MIT 许可分支，而非从零开始的原创实现。有关 上游归属、维护的修复和未答复的拉取请求，请参阅 CREDITS.md。

有关原始和当前贡献者声明，请参阅 LICENSE。

开发

npm ci
npm run build
npm test

真实的冒烟测试是可选加入的，因为它会修改一个可写看板，然后自行清理：

export PLANKA_BASE_URL="https://planka.example.com"
export PLANKA_AGENT_EMAIL="agent@example.com"
export PLANKA_AGENT_PASSWORD="<YOUR_PASSWORD>"
export PLANKA_SMOKE_BOARD_ID="1234567890123456789"
npm run test:smoke

在提交更改之前，请参阅 CONTRIBUTING.md。发布身份 集中在 project.identity.json 中；在您自己的命名空间下发布之前， 请更新它并运行 npm run sync:identity。