使用说明

克劳德的Planka MCP服务器

连接的MCP（模型上下文协议）服务器普兰卡 Claude.ai的看板用于人工智能驱动的项目管理。

此服务器公开全部 Planka v2 API作为MCP工具通过 可流式传输的HTTP 传输，使其与Claude.ai定制连接器兼容。

特性

75+MCP工具 覆盖所有Planka API终点
可流式HTTP传输 (POST /mcp + GET /mcp SSE）用于兼容Claude.ai
双重认证：API密钥（推荐）或电子邮件/密码，带401上的自动刷新
复合工具：董事会概述、项目概述、跨项目卡片搜索、“我的卡片”
多会话支持：每个Claude对话都有自己的MCP会话
Docker就绪：预构建图像 ghcr.io，多级Dockerfile+docker组合

先决条件

Node.js 20+
正在运行的Planka v2.x实例
A. 克劳德的Planka专用账户 （见下文）
A. 可公开访问的域 对于MCP服务器（例如。 https://planka-mcp.domain.tld)

快速开始

1.为Claude创建一个专用的Planka帐户

我们强烈建议创建一个 专用Planka用户帐户 特别是克劳德（例如。 claude@yourdomain.tld)，而不是使用您的个人帐户。这使得以下操作变得容易：

准确跟踪克劳德在活动日志中执行的操作
独立撤销Claude的访问权限，而不影响您自己的帐户
根据Claude的需求应用特定权限（管理员或成员）

2.安装依赖项

npm install

3.配置

cp .env.example .env
# Edit .env with your Planka URL and Claude's dedicated account credentials

身份验证选项 （选一个）：

方法	变量	注释
API密钥（推荐）	`PLANKA_API_KEY`	永不过期。通过生成 `planka_create_user_api_key` 工具
电子邮件+密码	`PLANKA_EMAIL` + `PLANKA_PASSWORD`	401自动刷新JWT

4.将服务器暴露在公共域中

Claude.ai要求MCP服务器可以通过HTTPS访问。你需要一个 公有领域 指向此服务器，例如：

https://planka-mcp.domain.tld

配置您的反向代理（Nginx、Traefik、Caddy…）以将HTTPS流量转发到 localhost:3001.

5.构建和运行

npm run build
npm start

6.验证

curl https://planka-mcp.domain.tld/health
# {"status":"ok","planka_url":"http://...","version":"1.0.0"}

7.添加到第.ai条

首选设置 > 连接器 > 添加自定义连接器
将URL设置为： https://planka-mcp.domain.tld/mcp

⚠️ URL 必须包括 /mcp 最后，Claude.ai将无法找到没有它的MCP服务器。
点击添加那么连接并通过OAuth屏幕进行授权
通过在对话中启用连接器 "+" 按钮> 连接器

码头工人

每次推送时，预构建的映像都会自动发布到GitHub容器注册表 main 在每个版本标签上(v*).

ghcr.io/nextheberg/planka-mcp-server-for-claude:latest

使用docker compose运行（推荐）

提供的 docker-compose.yml 默认情况下拉取预构建图像：

# Pull latest image and start
docker compose up -d

# Check logs
docker compose logs -f planka-mcp

直接用docker运行

docker run -d \
  --name planka-mcp \
  --restart unless-stopped \
  -p 3001:3001 \
  --env-file .env \
  ghcr.io/nextheberg/planka-mcp-server-for-claude:latest

本地建设

要从源构建图像而不是拉取图像，请执行以下操作：

# Edit docker-compose.yml: comment out `image:` and uncomment `build:`
docker compose up -d --build

或者直接：

docker build -t planka-mcp-server .

安全

即使MCP服务器暴露在公共域上，除了克劳德之外，任何人都无法访问它。原因如下：

需要OAuth --如果不完成OAuth流程（在浏览器中打开一个交互式弹出窗口），任何人都无法获得有效的令牌。没有人工干预，这种流程就无法自动化。
仅存储在内存中的令牌 --已发行的令牌仅存在于容器的RAM中。容器重新启动会立即使所有现有令牌无效。没有数据库，没有暴露的持久存储。
无令牌=401 --任何直接请求 /mcp 没有有效的Bearer令牌将立即被拒绝。
代币是不可测的 --格式 planka-mcp-token-{uuid}，UUID v4提供2¹²的可能值。

唯一现实的攻击面是传输中的令牌拦截——完全通过HTTPS/TLS缓解。OAuth发现端点(/.well-known/*, /oauth/authorize, /oauth/token)是公共的，但在未完成交互流的情况下不授予访问权限。

在实践中：只有克劳德之后你已单击“授权”--可以使用此服务器。

成本——使用克劳德·海库

管理Planka任务（创建卡片、更新列表、搜索板……）不需要一个强大的模型。这些是结构化的、低复杂性的操作，与 克劳德俳句，Anthropic最快、最实惠的车型。

使用Claude Haiku进行Planka操作的成本只是Claude Sonnet或Opus的一小部分，这使得这种连接器在日常项目管理自动化方面极具成本效益。

发展

npm run dev   # Uses tsx --watch for hot reload

环境变量

变量	必填	默认	描述
`PLANKA_BASE_URL`	是	-	Planka的完整URL（例如。 `http://192.168.1.50:3000`)
`PLANKA_API_KEY`	用于身份验证的	-	neneneba API密钥之一
`PLANKA_EMAIL`		-	密码验证电子邮件之一
`PLANKA_PASSWORD`		-	密码验证密码之一
`PORT`	没有	`3001`	服务器侦听端口
`NODE_TLS_REJECT_UNAUTHORIZED`	没有	`true`	设置为 `false` 用于自签名证书
`PLANKA_REQUEST_TIMEOUT`	没有	`30000`	请求超时（毫秒）
`LOG_LEVEL`	没有	`info`	日志级别：错误、警告、信息、调试

可用MCP工具（75+）

认证与系统

工具	说明
`planka_get_bootstrap`	获取Planka实例信息（版本、OIDC、限制）
`planka_get_config`	获取SMTP配置（管理员）
`planka_update_config`	更新SMTP配置（管理员）
`planka_test_smtp`	测试SMTP配置（管理员）

用户

工具	说明
`planka_list_users`	列出所有用户
`planka_create_user`	创建新用户
`planka_get_user`	获取用户详细信息
`planka_update_user`	更新用户设置
`planka_delete_user`	删除用户
`planka_update_user_email`	更改用户电子邮件
`planka_update_user_password`	更改用户密码
`planka_update_user_username`	更改用户名
`planka_create_user_api_key`	生成API密钥

项目

工具	说明
`planka_list_projects`	列出所有项目
`planka_create_project`	创建项目
`planka_get_project`	与董事会和成员一起获得项目
`planka_update_project`	更新项目设置
`planka_delete_project`	删除项目
`planka_add_project_manager`	添加项目经理
`planka_remove_project_manager`	删除项目经理
`planka_create_base_custom_field_group`	创建基本自定义字段组

板子

工具	说明
`planka_create_board`	创建一个板
`planka_get_board`	获取包含所有内容的板
`planka_update_board`	更新电路板设置
`planka_delete_board`	删除板
`planka_get_board_actions`	获取董事会活动日志
`planka_add_board_member`	添加董事会成员
`planka_update_board_member`	更新成员角色
`planka_remove_board_member`	移除董事会成员

列表

工具	说明
`planka_create_list`	创建列表
`planka_get_list`	用卡片获取列表
`planka_update_list`	更新列表（名称、颜色、位置、移动）
`planka_delete_list`	删除列表
`planka_sort_list`	按列表对卡片进行排序
`planka_move_list_cards`	将所有卡片移动到另一个列表
`planka_clear_list`	清除列表中的所有卡片

卡片

工具	说明
`planka_list_cards`	列出带过滤器的卡片
`planka_create_card`	创建卡片
`planka_get_card`	获取包含所有详细信息的卡片
`planka_update_card`	更新卡片（移动、重命名、到期日期等）
`planka_delete_card`	删除卡片
`planka_duplicate_card`	复制卡片
`planka_read_card_notifications`	将卡片通知标记为已读
`planka_get_card_actions`	获取卡活动日志

任务列表和任务

工具	说明
`planka_create_task_list`	在卡片上创建检查表
`planka_get_task_list`	获取包含任务的任务列表
`planka_update_task_list`	更新任务列表
`planka_delete_task_list`	删除任务列表
`planka_create_task`	创建任务
`planka_update_task`	更新任务（完成、分配、重命名）
`planka_delete_task`	删除任务

持卡会员

工具	说明
`planka_assign_user_to_card`	将用户分配到卡
`planka_unassign_user_from_card`	从卡中取消分配用户

工具	说明
`planka_list_comments`	列出卡片备注
`planka_create_comment`	添加评论
`planka_update_comment`	编辑评论
`planka_delete_comment`	删除评论

附件

工具	说明
`planka_add_link_attachment`	添加链接附件
`planka_update_attachment`	重命名附件
`planka_delete_attachment`	删除附件

自定义字段

工具	说明
`planka_update_base_custom_field_group`	更新基本字段组
`planka_delete_base_custom_field_group`	删除基本字段组
`planka_create_custom_field_in_base_group`	在基组中创建字段
`planka_create_board_custom_field_group`	创建板字段组
`planka_create_card_custom_field_group`	创建卡片字段组
`planka_get_custom_field_group`	获取字段组
`planka_update_custom_field_group`	更新字段组
`planka_delete_custom_field_group`	删除字段组
`planka_create_custom_field_in_group`	在组中创建字段
`planka_update_custom_field`	更新自定义字段
`planka_delete_custom_field`	删除自定义字段
`planka_update_custom_field_value`	在卡上设置字段值
`planka_delete_custom_field_value`	从卡中删除字段值

通知

工具	说明
`planka_list_notifications`	列出所有通知
`planka_get_notification`	获取通知详细信息
`planka_update_notification`	标记为已读/未读
`planka_read_all_notifications`	将所有内容标记为已读

通知服务

工具	说明
`planka_create_board_notification_service`	创建板webhook
`planka_create_user_notification_service`	创建用户webhook
`planka_update_notification_service`	更新通知服务
`planka_delete_notification_service`	删除通知服务
`planka_test_notification_service`	测试通知服务

网络钩子

工具	说明
`planka_list_webhooks`	列出所有Webhook
`planka_create_webhook`	创建webhook
`planka_update_webhook`	更新webhook
`planka_delete_webhook`	删除webhook

复合工具

工具	说明
`planka_get_board_overview`	全板视图：列表+卡片+成员+标签
`planka_get_project_overview`	每个列表中包含电路板和卡片数量的项目
`planka_search_cards_in_project`	在项目的所有方面搜索卡片
`planka_get_my_cards`	获取所有项目中分配给用户的所有卡片

用法示例（克劳德语中的自然语言）

“显示我的所有项目”
“创建一个名为“网站重新设计”的新项目”
“给我分配了什么卡片？”
“在开发板上的待办事项列表中添加一张卡‘修复登录错误’”
将所有卡片从“进行中”移动到“完成”
“在后端项目中搜索提到‘数据库’的卡”
在卡片X上创建一个包含以下项目的清单：设计、实施、测试
“将Y卡的到期日设置为下周五”
“在卡片Z上添加评论：'此内容已准备好审核'”
“显示主板的活动日志”

建筑

src/
  index.ts                  # Express HTTP server (Streamable HTTP transport)
  server.ts                 # MCP server definition + all 75+ tools
  planka/
    client.ts               # HTTP client (auth, auto-refresh, timeout)
    types.ts                # Full TypeScript type definitions
    api/
      auth.ts               # Access tokens + bootstrap
      projects.ts           # Projects + managers
      boards.ts             # Boards + memberships
      lists.ts              # Lists (CRUD + sort + move + clear)
      cards.ts              # Cards (CRUD + duplicate + notifications)
      task-lists.ts         # Task lists
      tasks.ts              # Tasks
      labels.ts             # Labels + card labels
      card-memberships.ts   # Card member assignments
      comments.ts           # Comments
      attachments.ts        # Attachments (link type)
      custom-fields.ts      # Custom field groups + fields + values
      users.ts              # Users (CRUD + email/password/username/apikey)
      notifications.ts      # Notifications
      notification-services.ts  # Notification services
      webhooks.ts           # Webhooks
      config.ts             # SMTP config

许可证

GPL-3.0许可证

工具	说明
`planka_create_label`	创建标签
`planka_update_label`	更新标签
`planka_delete_label`	删除标签
`planka_add_label_to_card`	为卡片添加标签
`planka_remove_label_from_card`	从卡上删除标签