Planka MCP

planka-mcp

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

阅读西班牙语版

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

警告

旧版 @gogogadgetbytes/planka-mcp 软件包可能会在 Planka 2.x 上报告成功，实际却什么也没做。在替换现有安装前，请阅读五个静默失败的注意事项。

MCP 新手？请先阅读

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

要求

• Node.js 18 或更高版本，以及 npx
• 可访问的 Planka 2.x 实例
• 能查看目标项目和看板的专用 Planka 用户
• 一个 MCP 客户端：Claude Code、Codex CLI、Cursor 或 VS Code
• 仅当设置过程需要创建看板时，才需要项目经理角色

支持 Linux 和 macOS。无需 Bun 运行时。

安装

每个客户端只需一条命令。所有命令都会通过 npx 运行已发布的软件包，因此无需克隆或构建。

客户端	单行命令
Claude Code（插件：MCP + 技能 + 预检）	/plugin marketplace add omnicoreos/planka-mcp 然后运行 /plugin install planka@planka-mcp
Claude Code（仅服务）	claude mcp add --scope user --transport stdio planka --env PLANKA_BASE_URL=https://planka.example.com --env PLANKA_API_KEY=<key> -- npx -y @omnicoreos/planka-mcp
Codex CLI	codex mcp add planka -- npx -y @omnicoreos/planka-mcp（然后添加下方的 env 块）
Cursor
VS Code
任一客户端，交互式引导	npx @omnicoreos/planka-mcp init --client claude|codex|cursor|vscode|print

Cursor 和 VS Code 链接都使用占位密钥，而不是真实密钥：深层链接会留在浏览器历史记录中。两个客户端都会自行询问凭据——VS Code 通过 promptString 输入项询问，因此提交到仓库的 .vscode/mcp.json 不会包含任何机密。

planka-mcp init

npx @omnicoreos/planka-mcp init --client claude     # claude mcp add, user scope
npx @omnicoreos/planka-mcp init --client codex      # appends to ~/.codex/config.toml
npx @omnicoreos/planka-mcp init --client cursor     # merges ~/.cursor/mcp.json (0600) + prints the deeplink
npx @omnicoreos/planka-mcp init --client vscode     # writes .vscode/mcp.json with a secret prompt
npx @omnicoreos/planka-mcp init --client print      # prints every snippet, writes nothing

连接终端时，该命令会询问所需信息；使用 --base-url、--api-key、--board、--email 和 --password 可改为非交互模式。在写入任何内容前，它会执行一次经过身份验证的 GET /api/users/me，以此检查基础 URL 是否指向 SPA 而非 API，或凭据是否从未生效。--dry-run 会打印精确的变更内容，但不会修改任何内容。

所有配置生成器都会合并配置：如果已有 planka 条目，会报告该条目并保持不变；同一文件中的其他服务也会予以保留。写入主目录的文件会设置为 0600 权限。

./scripts/setup.sh 等同于 init --client claude。较旧的交互式安装程序仍可使用——它还会选择或创建看板，并运行完整的创建/标签/评论/删除冒烟测试——命令是 node scripts/setup.mjs。

Claude Code 插件

该插件会安装 MCP 服务、两个工作流技能，以及一个 SessionStart 预检程序，可在首次调用工具前检查是否缺少凭据或基础 URL 是否以 http:// 开头：

/plugin marketplace add omnicoreos/planka-mcp
/plugin install planka@planka-mcp

启用插件时，Claude Code 会询问基础 URL 和 API 密钥，并将密钥存储在操作系统密钥链中，而不是 settings.json 中。Codex 通过 .codex-plugin/plugin.json 和 .agents/plugins/marketplace.json 读取同一仓库。

插件无法附带权限规则，这是唯一无法随插件迁移的内容：请改用 PLANKA_READ_ONLY 和 PLANKA_DISABLED_TOOLS（见下文），而不要使用客户端拒绝列表——它们适用于每种运行时，且不占用上下文。

Codex env 块

codex mcp add 不接受凭据，因此请将凭据添加到 ~/.codex/config.toml（或让 init --client codex 来完成）：

[mcp_servers.planka]
command = "npx"
args = ["-y", "@omnicoreos/planka-mcp"]
env = { PLANKA_BASE_URL = "https://planka.example.com", PLANKA_API_KEY = "<key>" }

验证是否正常工作

首先，检查 Claude Code 的配置：

claude mcp list
claude mcp get planka

然后完全重启 Claude Code——MCP 服务会在会话开始时加载。如果你在项目的 .mcp.json 中配置了服务，请在该项目中打开 Claude Code，并在出现提示时批准项目范围的服务。如果你安装了插件，/plugin 会显示该插件，其 Errors 标签页会显示启动失败的服务。

向 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 看不到这些工具，请先重启，然后按照 故障排除中的说明操作。

身份验证

有两种身份验证方式，且互斥：同时设置两者会导致配置错误，因为 Planka 会优先读取 Authorization，并在两者同时传入时静默忽略 x-api-key。

	PLANKA_API_KEY（推荐）	PLANKA_AGENT_EMAIL + PLANKA_AGENT_PASSWORD
发送方式	每个请求都携带 X-Api-Key: <prefix>_<secret>	POST /api/access-tokens，然后使用 Authorization: Bearer
登录往返	无	每个会话一次，每 25 分钟刷新
登录速率限制	不受此限制	每个身份每 60 秒最多登录 10 次——多个 Agent 同时启动时很快就会达到上限
磁盘上的密码	无	有，存储在客户端的配置文件中
附件下载	可用	可用

操作步骤：使用 API 密钥创建受限范围的 Agent 用户

以下四个步骤由 Planka 管理员执行。最终创建的用户只能查看你指定的看板——这由 Planka 本身强制执行，而不是由此服务强制执行。

1. 创建全局角色最低的用户。 在 Planka 界面中： Administration → Users → Add user，角色选 boardUser。boardUser 无法创建项目，也无法为自己授予成员资格。

2. 仅为它授予需要处理的看板的成员资格：

   curl -X POST "$PLANKA_URL/api/boards/<BOARD_ID>/board-memberships" \
     -H "Authorization: Bearer $ADMIN_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"userId":"<USER_ID>","role":"editor"}'
   

   如果要让 Agent 读取和评论，但绝不创建或移动卡片，请使用 "role":"viewer"。GET /api/projects 随后只会返回这些成员资格对应的项目；访问其他任何看板都会返回 404。

3. 签发 API 密钥（仅限管理员的端点）。密钥只会显示一次，位于 included.apiKey 中；Planka 只存储其哈希和前缀：

   curl -X POST "$PLANKA_URL/api/users/<USER_ID>/api-key" \
     -H "Authorization: Bearer $ADMIN_TOKEN"
   

4. 仅使用该密钥配置服务，不添加其他内容。 删除 PLANKA_AGENT_EMAIL 和 PLANKA_AGENT_PASSWORD：

   {
     "mcpServers": {
       "planka": {
         "command": "npx",
         "args": ["-y", "@omnicoreos/planka-mcp"],
         "env": {
           "PLANKA_BASE_URL": "https://planka.example.com",
           "PLANKA_API_KEY": "abcd1234_0123456789abcdef0123456789abcdef"
         }
       }
     }
   }
   

轮换密钥时，重新执行步骤 3：签发新密钥会使旧密钥失效。

限定服务范围

API 密钥继承其用户的权限——密钥本身没有作用域。因此，范围限定分为三层，每一层都能涵盖其他层无法涵盖的内容。

Layer 1 · PLANKA          the only layer an agent cannot talk its way around
  boardUser + board memberships + the API key above
  ⇒ everything outside the allowed boards is 404/403 at the API

Layer 2 · THIS SERVER     ergonomics, and defence against the agent itself
  the environment variables below; they travel with the package,
  so Claude Code, Codex and Cursor all get the same rules

Layer 3 · THE CLIENT      survives a downgrade of this package
  .claude/settings.json deny/ask rules, Codex enabled_tools/disabled_tools

第 1 层有实际的强制约束，但无法表达“不要调用 planka_get_board，它会多消耗四十倍上下文”。第 2 层可以表达，并适用于每种运行时。即使此软件包回退到较旧版本，第 3 层仍然有效。

第 2 层：环境变量

变量	值	作用
PLANKA_DEFAULT_BOARD_ID	一个看板 ID	所有需要 boardId 的工具都可省略该参数，并默认使用此看板。这样 Agent 无需仅为获取一个始终不变的 ID 而调用 planka_get_structure
PLANKA_ALLOWED_BOARD_IDS	以逗号分隔的看板 ID	不在列表中的看板会从 planka_get_structure 的结果中过滤掉；任何指定这些看板的调用都会在请求离开进程前被拒绝
PLANKA_ALLOWED_PROJECT_IDS	以逗号分隔的项目 ID	同上，但作用于上一级
PLANKA_READ_ONLY	true 或 1	二十七个写入工具会从 tools/list 中消失，即使被调用也会遭拒
PLANKA_HIDE_DEPRECATED	true 或 1	从 tools/list 中移除七个已弃用工具（manage_labels、manage_lists、manage_comment、add_comment、get_board、list_cards、list_lists），节省约 6.8 kB 的上下文。它们仍可调用，因此缓存的工具列表仍然有效
PLANKA_DISABLED_TOOLS	以逗号分隔的工具名称	关闭指定的工具。planka_ 前缀可选：get_board 和 planka_get_board 表示同一个工具
PLANKA_PROTECTED_LIST_IDS	以逗号分隔的列表 ID	拒绝在这些列表中创建或移动卡片、编辑或删除这些列表，以及将卡片移出这些列表、归档或删除卡片
PLANKA_SUMMARY_DECISION_LISTS	以逗号分隔的列名称或 ID	调用未指定时，planka_board_summary 返回哪些列中的卡片。未设置：不返回卡片，只返回看板的结构
PLANKA_SUMMARY_HIGHLIGHT_LABEL	一个标签名称	在 planka_board_summary 中标记卡片未受阻的标签。未设置：不突出显示任何内容
PLANKA_MCP_PREFLIGHT	full	仅由插件的 SessionStart hook 读取：也启动服务二进制文件并等待其 stdio 横幅。默认关闭，因为在缓存为空时会产生一次 npx 下载
PLANKA_MCP_COMMAND	一条命令	由同一个 hook 读取：指定要启动的命令，以替代 npx -y @omnicoreos/planka-mcp（本地检出版本或固定版本的二进制文件）

**服务本身不包含任何看板词汇。**列名称和“ready”标签由你用自己的语言定义：最后两个变量用于告知摘要看板的结构。如果提示不匹配任何内容，结果会在 warnings 中返回，而不会给出空答案。

"PLANKA_SUMMARY_DECISION_LISTS": "decision,probalo,miralo",
"PLANKA_SUMMARY_HIGHLIGHT_LABEL": "decidido"

**允许列表依据 ID，而不是名称。**任何看板编辑者都可以重命名看板，因此基于名称的允许列表只需一次编辑就能绕过。Planka ID 是稳定的。

关于这些设置的作用与限制，有两点说明：

• PLANKA_READ_ONLY 会隐藏工具，但不会让账户变为只读。如果你确实需要只读账户，请将它与上文第 2 步中的 "role":"viewer" 搭配使用。
• PLANKA_PROTECTED_LIST_IDS 是一道防护措施，不是权限设置：Planka 不支持按列表设置权限。它适用于“不要自行将卡片移到 Merged”，但不适用于任何对安全至关重要的场景。

示例——一个只读取单个看板并发表评论、不做其他操作的 Agent：

"env": {
  "PLANKA_BASE_URL": "https://planka.example.com",
  "PLANKA_API_KEY": "abcd1234_0123456789abcdef0123456789abcdef",
  "PLANKA_DEFAULT_BOARD_ID": "1234567890123456789",
  "PLANKA_ALLOWED_BOARD_IDS": "1234567890123456789",
  "PLANKA_DISABLED_TOOLS": "get_board",
  "PLANKA_PROTECTED_LIST_IDS": "9876543210987654321"
}

41 个工具

ID 是字符串。先调用 planka_get_structure，然后使用 Planka 返回的 ID；不要猜测 ID。

工具	功能
planka_get_structure	列出可见的项目、看板和列表
planka_get_board	已弃用。 读取整个看板，最多读取 limit 张卡片
planka_board_summary	一次调用即可获取概览：列及其计数、带 ID 的标签，以及可选的指定列中的卡片
planka_find_cards	唯一的卡片读取工具：读取一个列（listId），或按文本、标签或成员搜索一个看板
planka_list_lists	已弃用。 planka_board_summary 的别名，cardsFrom: []
planka_list_cards	已弃用。 带 listId 的 planka_find_cards 别名
planka_create_card	创建卡片，并可添加任务和标签
planka_get_card	卡片摘要；可按需设置 detail: "full" 和 withComments
planka_update_card	更新标题、描述、到期日期或完成状态
planka_move_card	将卡片移动到其他列表或位置
planka_delete_card	永久删除卡片
planka_create_tasks	为卡片添加清单任务
planka_update_task	重命名任务或将其标记为已完成
planka_delete_task	删除任务
planka_create_label	创建看板标签
planka_update_label	重命名标签或更改其颜色
planka_delete_label	从看板及其所有卡片中删除标签
planka_manage_labels	已弃用。 将 action 路由到上述三个工具的别名
planka_set_card_labels	添加或移除标签，并验证最终状态
planka_create_comment	通过 Planka 2.x 专用端点添加评论
planka_get_comments	分页获取评论（limit、beforeId、all）
planka_update_comment	改写现有评论
planka_delete_comment	删除评论
planka_add_comment	已弃用。 planka_create_comment 的别名
planka_manage_comment	已弃用。 将 action 路由到更新或删除操作的别名
planka_create_list	在看板上创建列表（列）
planka_update_list	重命名列、调整其位置或更改其分类
planka_delete_list	删除一列及其中的所有卡片
planka_manage_lists	已弃用。 将 action 路由到上述三个工具的别名
planka_add_attachment	将本地文件上传到卡片，并验证文件已成功添加
planka_get_attachments	列出卡片附件及其类型、大小和下载 URL
planka_view_attachment	返回附件内容；图像会以可查看的形式返回
planka_delete_attachment	删除附件
planka_card_history	以易读条目显示一张卡片的活动日志：创建、移动、分配、任务完成
planka_board_activity	按卡片分组，列出看板自指定日期以来的移动情况
planka_set_card_members	分配或取消分配人员，并验证最终成员状态
planka_list_users	列出可分配的人员，并提供按看板范围限定的备用方案
planka_whoami	此服务的账户、看板角色、Planka 版本和访问策略
planka_duplicate_card	复制卡片及其任务、标签和成员
planka_archive_card	将卡片归档到看板的隐藏归档区，或还原卡片
planka_move_list_cards	将一列中的所有卡片移动到另一列，并显示计数
读取遵循一个原则：默认提供简短摘要，详情通过参数获取。planka_board_summary 一次调用即可开启会话；传入 listId 的 planka_find_cards 会通过一次 GET /api/lists/:id 请求读取整列，因此 total 就是该列的实际大小，且返回结果会携带 truncated: false；不传 listId 时，同一工具会搜索看板。在包含 185 张卡片的参考看板上，弃用的 planka_get_board 从 56,112 个字符缩减至 17,215 个字符，planka_get_structure（withLists: false）从 696 个缩减至 203 个；而一个包含 159 张卡片的列，所需请求数从五次降至两次。每次读取都会报告 total、returned 和 hasMore，因此被截断的回答不会看起来像是完整结果；每次基于看板的读取也都会携带 excludesArchived: true，因为 Planka 在读取看板时会排除归档和回收站内容。

每个输入字段以及每个工具的完整载荷都列在工具参考中。

客户端连接后会了解什么

initialize 握手会返回一组简短的服务端说明——如何开启会话、ID 的来源、为什么卡片上的每条评论都很重要，以及 Planka 在本应返回 403 时会返回 404。Claude Code 会将这些说明放入会话系统提示词中，Codex CLI 则会与工具列表一同读取，因此共享指南只需说明一次，无需在 41 个工具描述中反复重述。每个工具还会明确发布显示标题和全部四项 MCP 行为提示，而不是继承规范中偏保守的默认值；此外还包含 Claude Code 会处理的两个 _meta 键：对会删除数据的工具强制显示确认提示，并提高 planka_view_attachment 的输出上限。详情请参阅服务端说明和注解。

资源和提示词

另外还有两个接口，只有在有人请求时才会产生开销；因此，篇幅较长的指南放在这里，而不是放进每次会话都要付费读取的说明中。Claude Code 和 Cursor 都会读取这两类内容；Codex 两者都不支持，因此这里的内容并非关键依赖。

资源提供随软件包一同发布的指南。在 Claude Code 中，可以通过 @ 提及；在 Cursor 中，则可从资源选择器中获取：

URI	内容
planka://workflow/readme	可选的看板工作流：列、标签以及由谁移动哪些内容
planka://workflow/board-template	在新看板上创建的列和标签
planka://workflow/skills/orchestrator	主管技能，原文提供
planka://workflow/skills/close-card	关闭技能，原文提供
planka://gotchas/planka-2x	Planka 2.x 在调用返回无意义内容时的实际行为
planka://labels/colors	planka_create_label 和 planka_update_label 接受的所有颜色，由架构生成

提示词提供三种启动方式，Claude Code 会将其显示为 /mcp__planka__<name>：

提示词	参数	作用
planka-open-session	boardId?、since?	依次提供摘要、近期动态和重要列
planka-close-card	cardId、listId?	阅读完整讨论串，撰写如实的结项评论，移动卡片，并检查 verified
planka-board-triage	boardId?、lists?	遍历等待人员处理的列，并将每张卡片转化为一个问题

可选的 Agent 工作流

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

分层采用：

1. 只使用 MCP 工具。
2. 添加看板状态、卡片模板和人工交接机制。
3. 为每张卡片添加一个 worktree，并由主管协调工作者。

从一个能延续到会话结束之后的看板开始。看板模板、可复制的 Claude Code 技能以及可选的 worktree 助手都是独立组件。

故障排除

• 症状、原因和具体修复方法
• 为什么 Planka 2.x 会导致较旧的 MCP 服务静默失效
• 完整的工具负载

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

致谢和许可证

这是基于 gogogadgetbytes/planka-mcp 的 MIT 许可分支，并非从头开始实现的原创项目。上游署名、维护的修复以及尚未处理的拉取请求，请参阅 CREDITS.md。

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

开发

npm ci
npm run build
npm test

真实冒烟测试需选择启用，因为它会修改一个可写看板，然后自行清理。它通过标准输入/输出驱动全部 41 个工具，并将每次写入与原始 Planka API 交叉核对，包含 90 多项具名检查：

export PLANKA_BASE_URL="https://planka.example.com"
export PLANKA_AGENT_EMAIL="[email protected]"
export PLANKA_AGENT_PASSWORD="<YOUR_PASSWORD>"
export PLANKA_SMOKE_BOARD_ID="1234567890123456789"
npm run test:smoke

npm run test:smoke 会先进行构建，因此无法测试过时的 dist/。可通过四个可选变量进行调整：

变量	作用
PLANKA_SMOKE_LIST_ID	创建临时卡片的列表。不设置时，会选择一个名称看起来像临时列表的列表；若没有，则使用第一个列表
PLANKA_SMOKE_FAIL_AFTER	在检查 <n> 后注入故障，以验证清理仍会运行
PLANKA_MCP_ENTRY	服务入口点。默认为 dist/index.js
VERBOSE	设为 1 可打印每项检查的负载

提交更改前，请参阅 CONTRIBUTING.md。发布身份信息集中在 project.identity.json 中；若要使用自己的命名空间发布，请先更新该文件并运行 npm run sync:identity。