Planka MCP Server For Claude

克劳德的Planka MCP服务器

](https://github.com/NextHeberg/Planka-MCP-Server-for-Claude/actions/workflows/docker-publish.yml)

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

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

目录

• 特性
• 先决条件
• 快速开始
• 码头工人
• 安全
• 成本——使用克劳德·海库
• 发展
• 环境变量
• 可用MCP工具（75+）
• 使用示例
• 建筑
• 许可证

特性

• 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

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

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条

1. 首选 设置 > 连接器 > 添加自定义连接器

1. 将URL设置为： https://planka-mcp.domain.tld/mcp

> ⚠️ URL 必须包括 /mcp 最后，Claude.ai将无法找到没有它的MCP服务器。

1. 点击 添加那么 连接 并通过OAuth屏幕进行授权

1. 通过在对话中启用连接器 "+" 按钮> 连接器

码头工人

每次推送时，预构建的映像都会自动发布到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

环境变量

可用MCP工具（75+）

认证与系统

用户

项目

板子

列表

卡片

任务列表和任务

标签

持卡会员

评论

附件

自定义字段

通知

通知服务

网络钩子

复合工具

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

• “显示我的所有项目”
• “创建一个名为“网站重新设计”的新项目”
• “给我分配了什么卡片？”
• “在开发板上的待办事项列表中添加一张卡‘修复登录错误’”
• 将所有卡片从“进行中”移动到“完成”
• “在后端项目中搜索提到‘数据库’的卡”
• 在卡片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许可证