AI导哈

看板AI交互服务

Planka MCP Server 是一个使AI助手（如Claude、VS Code Copilot等）能够与Planka看板应用进行交互的服务。

  • by chmald
  • TypeScript
  • 混合部署
  • 6 星标
  • 更新于
在 GitHub 查看 chmald/planka-mcp

使用说明

Planka MCP服务器

MCP服务器，使AI助手（Claude、VS Code Copilot等）能够与 普兰卡 -实时看板应用程序。

快速开始

先决条件

  • Node.js 18+ 或 码头工人
  • Planka实例 运行和可访问
  • Planka用户帐户 具有适当的权限

克劳德桌面版

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "planka": {
      "command": "npx",
      "args": ["@chmald/planka-mcp"],
      "env": {
        "PLANKA_BASE_URL": "http://localhost:3000",
        "PLANKA_API_KEY": "your-api-key"
      }
    }
  }
}

VS代码

添加 .vscode/mcp.json:

{
  "servers": {
    "planka": {
      "type": "stdio",
      "command": "npx",
      "args": ["@chmald/planka-mcp"],
      "env": {
        "PLANKA_BASE_URL": "http://localhost:3000",
        "PLANKA_API_KEY": "your-api-key"
      }
    }
  }
}

码头工人

{
  "mcpServers": {
    "planka": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "PLANKA_BASE_URL=http://host.docker.internal:3000",
        "-e", "PLANKA_API_KEY=your-api-key",
        "chmald/planka-mcp:latest"
      ]
    }
  }
}

注： 使用 host.docker.internal 而不是 localhost 运行Docker时。

配置

环境变量

变量 必填 默认 描述
PLANKA_BASE_URL 是的 http://localhost:3000 您的Planka实例URL
PLANKA_API_KEY 没有* - Planka API密钥作为发送 X-Api-Key
PLANKA_USERNAME 否* - Planka用户名或电子邮件
PLANKA_PASSWORD 无* - Planka密码
MCP_TRANSPORT 没有 stdio MCP传输模式： stdio 或 sse
MCP_PORT 没有 3001 HTTP端口在以下情况下使用 MCP_TRANSPORT=sse
PLANKA_HTTP_MAX_RETRIES 没有 2 每次请求的瞬时HTTP/网络故障的最大重试次数
PLANKA_HTTP_RETRY_BASE_DELAY_MS 没有 250 基本重试延迟（毫秒）（指数回退）
ENABLE_ALL_TOOLS 没有 false 启用所有27个工具
ENABLE_ADMIN_TOOLS 没有 false 启用管理工具
ENABLE_OPTIONAL_TOOLS 没有 false 启用可选工具

*需要身份验证。提供其中之一 PLANKA_API_KEY，或两者皆有 PLANKA_USERNAME 和 PLANKA_PASSWORD.

身份验证模式

  • API密钥（推荐）： 集 PLANKA_API_KEY.
  • 用户名/密码： 集 PLANKA_USERNAME 和 PLANKA_PASSWORD.
  • 如果两者都已设置，服务器将使用 PLANKA_API_KEY.

重试行为

  • 重试适用于瞬态故障(408, 429, 5xx)以及网络请求错误。
  • 延迟使用指数回退： PLANKA_HTTP_RETRY_BASE_DELAY_MS * 2^attempt.
  • PLANKA_HTTP_MAX_RETRIES 控制初始请求后的其他尝试。

工具类别

默认情况下， 10个核心工具 用于基本的看板操作：

类别 工具 描述
核心 10 授权、项目、板、列表、卡片、任务、评论、标签（始终启用）
可选的 13 附件、自定义字段、通知等。
管理员 4 用户管理、webhooks、配置

启用更多工具：

"env": {
  "ENABLE_ALL_TOOLS": "true"
}

可用工具

每个工具都使用 action 参数。例子： { "action": "list" } 或 { "action": "get", "id": "123" }

Core Tools (always enabled)
工具 操作
auth login, logout, acceptTerms, oidcExchange, revokePending, getTerms
bootstrap get -获取应用程序数据、用户信息、项目
projects list, get, create, update, delete
boards get, create, update, delete
lists get, create, update, delete
cards list, get, create, update, delete
comments list, create
tasks getList, createList, create, update
labels create, update, delete, addToCard, removeFromCard
cardMembers add, remove
Admin Tools (ENABLE_ADMIN_TOOLS=true)
工具 操作
config get, update, testSmtp
users list, create, update, delete, updateEmail, updatePassword等等。
webhooks list, create, update, delete
projectManagers add, remove
Optional Tools (ENABLE_OPTIONAL_TOOLS=true)
工具 操作
attachments create, update, delete
boardMembers add, update, remove
customFields createBaseGroup, createField, setValue等等。
notifications list, get, markRead, markAllRead, markCardRead, createUserService, createBoardService, updateService, deleteService, testService
actions boardActions, cardActions
cardExtras duplicate
commentExtras update, delete
listExtras clear, moveCards, sort
taskExtras updateList, deleteList, deleteTask
labelExtras update, delete, removeFromCard
cardMemberExtras remove
backgroundImages upload, delete
userInfo get

多客户端模式（SSE）

对于多个客户端共享一台服务器的团队部署：

docker run -d \
  --name planka-mcp \
  -p 3001:3001 \
  -e MCP_TRANSPORT=sse \
  -e PLANKA_BASE_URL=http://your-planka-server:3000 \
  -e PLANKA_API_KEY=your-api-key \
  chmald/planka-mcp:latest

将客户端连接到 http://localhost:3001/sse.

故障排除

“身份验证失败”

  • 验证您的API密钥（或用户名/密码）是否正确
  • 检查一下 PLANKA_BASE_URL 可访问的

Docker“拒绝连接”

  • 使用 host.docker.internal 而不是 localhost
  • 确保Planka正在运行

npx失败

  • 确保已安装Node.js 18+： node --version
  • 尝试： npm cache clean --force

调试日志

npx @chmald/planka-mcp 2>&1 | tee debug.log

升级说明

检查 更改日志.md 查看完整版本的详细信息。

升级到2.0.3

  • 这 auth 工具从可选工具转移到核心工具，现在始终可用。
  • API密钥身份验证现在支持 PLANKA_API_KEY (X-Api-Key).
  • 如果配置了API密钥和用户名/密码， PLANKA_API_KEY 使用。

链接

许可证

麻省理工学院-见 许可证

相关 MCP