使用说明

木板mcp

A. 模型上下文协议（MCP）暴露的服务器地板 2 看板操作作为人工智能资源和工具。

使用Laravel 12和FrankenPHP构建，在Docker中以Octane工作模式运行。多租户：每个MCP客户端为每个请求提供自己的Planka API密钥-服务器端不存储凭据。

资源

MCP资源是Planka数据的只读、URI寻址视图。MCP客户端可以通过URI直接读取它们。

系统

资源	URI
配置	`planka://config`
独自创立 `planka://bootstrap`

结构

资源	URI
结构	`planka://structure`
项目	`planka://projects`
项目	`planka://projects/{projectId}`

板子

资源	URI
董事会	`planka://boards/{boardId}`
董事会行动	`planka://boards/{boardId}/actions`

列表

资源	URI
列表	`planka://lists/{listId}`
列表卡片	`planka://lists/{listId}/cards`

卡

资源	URI
卡片	`planka://cards/{cardId}`
卡片评论	`planka://cards/{cardId}/comments`
卡片操作	`planka://cards/{cardId}/actions`

任务

资源	URI
任务列表	`planka://task-lists/{taskListId}`

自定义字段

资源	URI
自定义字段组	`planka://custom-field-groups/{groupId}`

用户

资源	URI
用户	`planka://users`
用户	`planka://users/{userId}`

通知

资源	URI
通知	`planka://notifications`
通知	`planka://notifications/{notificationId}`

网络钩子

资源	URI
Webhooks	`planka://webhooks`

工具

结构

工具	说明
`planka_get_structure`	获取所有项目及其董事会和列表
`planka_get_board`	找一块有所有列表、卡片和标签的板

项目

工具	说明
`planka_manage_projects`	创建、获取、更新或删除项目
`planka_manage_project_managers`	添加或删除项目经理

板子

工具	说明
`planka_manage_boards`	在项目中创建、获取、更新或删除电路板
`planka_manage_board_memberships`	添加、更新或删除董事会成员资格

列表

工具	说明
`planka_manage_lists`	在板上的列表中创建、获取、更新、删除或管理卡片
`planka_sort_list`	按指定字段对列表中的卡片进行排序

卡

工具	说明
`planka_create_card`	创建新卡，可选任务
`planka_get_card`	获取完整的卡片详细信息，包括任务、评论、标签和附件
`planka_update_card`	更新卡片的名称、描述、到期日期或完成状态
`planka_move_card`	将卡片移动到其他列表或位置
`planka_delete_card`	永久删除卡片
`planka_duplicate_card`	将现有卡复制到同一列表中
`planka_manage_card_membership`	添加或删除用户作为卡的成员

任务

工具	说明
`planka_create_tasks`	在卡片上添加一个或多个清单项目
`planka_update_task`	更新任务的名称或完成状态
`planka_delete_task`	从卡片中删除任务
`planka_update_task_list`	更新任务列表的名称
`planka_delete_task_list`	从卡片中删除任务列表及其所有任务

工具	说明
`planka_add_comment`	在卡片上添加评论（支持标记）
`planka_get_comments`	在卡片上获取所有评论
`planka_update_comment`	更新现有评论的文本
`planka_delete_comment`	从卡片中删除评论

附件

工具	说明
`planka_upload_attachment`	将文件附件上传到卡上
`planka_manage_attachments`	更新或删除卡上的附件

用户

工具	说明
`planka_manage_users`	列出、获取、创建、更新或删除用户
`planka_manage_user_credentials`	更新用户的电子邮件、密码或用户名

通知

工具	说明
`planka_get_notifications`	列出已验证用户的所有通知
`planka_mark_notification_read`	将通知标记为已读或未读
`planka_mark_all_notifications_read`	将所有通知标记为已读

自定义字段

工具	说明
`planka_manage_custom_field_groups`	在项目、电路板或卡片上创建、获取、更新或删除自定义字段组
`planka_manage_custom_fields`	在自定义字段组中创建、更新或删除自定义字段
`planka_manage_custom_field_values`	设置或删除卡片上的自定义字段值

网络钩子

工具	说明
`planka_manage_webhooks`	列出、创建、更新或删除Webhook

活动

工具	说明
`planka_get_actions`	获取板或卡的活动日志（操作）

通知服务

工具	说明
`planka_manage_notification_services`	为用户或板创建、更新、测试或删除通知服务（集成）

需求

Docker和Docker Compose
正在运行的Planka 2实例
Planka API密钥（根据 设置→ API密钥)

生产部署

使用Docker Compose（推荐）

复制示例环境文件并填写您的值：

cp .env.production.example .env.production
# Edit .env.production — set APP_KEY and PLANKA_URL

生成应用程序密钥：

docker run --rm ghcr.io/mintopia/planka-mcp:latest php artisan key:generate --show
# Paste the output into .env.production as APP_KEY

使用生产Compose文件启动服务器：

docker compose -f docker-compose.prod.yml up -d

服务器正在监听 http://localhost:8080MCP终点位于 /mcp.

要提取最新图像，请执行以下操作：

docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

使用 `docker run`

docker run -d \
  --name planka-mcp \
  --restart unless-stopped \
  -p 8080:80 \
  -e APP_KEY=base64:$(openssl rand -base64 32) \
  -e PLANKA_URL=https://your-planka-instance.example.com \
  ghcr.io/mintopia/planka-mcp:latest

环境变量

变量	必填	描述
`PLANKA_URL`	是	您的Planka实例的基本URL（例如。 `https://planka.example.com`)
`APP_KEY`	是	Laravel应用程序密钥——使用生成 `php artisan key:generate --show`
`APP_URL`	否	此服务器的公共URL（在生成的配置示例中使用）
`APP_ENV`	没有	`production` （默认）或 `local`
`REDIS_HOST`	否	Redis主机名--默认为 `redis` 在Docker Compose中， `127.0.0.1` 否则
`REDIS_PORT`	否	Redis端口--默认为 `6379`
`REDIS_PASSWORD`	否	Redis密码——默认为无

Planka API的关键在于从不配置服务器端。每个客户端在每次请求时都会传递它（请参见认证在......下面

Webhook订阅（可选）

Webhook订阅支持允许Planka将事件通知推送到服务器，以便在以下情况下转发给MCP客户端 laravel/mcp 添加 resources/subscribe 支持。

变量	必填	描述
`SUBSCRIPTION_ENABLED`	否	设置为 `true` 启用webhook端点--默认为 `false`
`PLANKA_WEBHOOK_SECRET`	建议使用	HMAC-SHA256密钥来验证传入的webhook签名。应始终在以下情况下设置 `SUBSCRIPTION_ENABLED=true`

认证

对MCP服务器的每个请求都必须包含Planka API密钥。接受两种标头格式：

Authorization: Bearer <planka-api-key>

X-Api-Key: <planka-api-key>

如果两个报头都存在， Authorization: Bearer 优先。

若要获取API密钥，请登录Planka并转到 设置→ API密钥→ 创建API密钥.

配置Claude代码

将服务器添加到您的Claude Code MCP配置中。配置文件为 ~/.claude/mcp.json （或使用 claude mcp add).

mcp.json

{
  "mcpServers": {
    "planka": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer <your-planka-api-key>"
      }
    }
  }
}

命令行界面

claude mcp add --transport http planka http://localhost:8080/mcp \
  --header "Authorization: Bearer <your-planka-api-key>"

替换 localhost:8080 如果服务器是远程部署的，则使用实际主机和端口。

配置Claude桌面

在 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "planka": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer <your-planka-api-key>"
      }
    }
  }
}

健康检查

curl http://localhost:8080/health
# → OK

发展

需求

PHP 8.3+
作曲家

本地设置（无Docker）

composer install
npm install
npm run build
php artisan key:generate

编辑 .env 并设置 PLANKA_URL 到你的Planka实例。

运行测试

本地：

# Build assets (required before tests)
npm run build

# Run the test suite
composer test

# Run with HTML coverage report + clover.xml (outputs to storage/coverage/)
composer test-coverage

通过Docker （不需要本地PHP——XDebug始终存在于开发映像中）：

# Run the test suite
docker compose run --rm --no-deps planka-mcp composer test

# Run with coverage
docker compose run --rm --no-deps planka-mcp composer test-coverage

HTML报告将写入 storage/coverage/index.html。跑步后打开它：

open storage/coverage/index.html       # macOS
xdg-open storage/coverage/index.html  # Linux

静态分析

# Natively
composer analyse

# Via Docker
docker compose run --rm --no-deps planka-mcp composer analyse

Docker开发设置

docker-compose.yml 配置用于本地开发：

建筑来自 Dockerfile.dev --包括XDebug、单请求工作模式
Bind将项目目录挂载到容器中 /app （无命名卷——Composer依赖项在首次启动时由入口点脚本安装）
暴露 host.docker.internal 因此XDebug可以连接回IDE

启动开发服务器：

PLANKA_URL=https://your-planka-instance.example.com docker compose up

或者导出变量：

export PLANKA_URL=https://your-planka-instance.example.com
docker compose up

开发映像已配置为自动热重新加载-- 更改源代码时不需要重新启动容器:

watch 在开发Caddyfile中，告诉FrankenPHP注意 app/**/*.php 和 config/**/*.php 用于更改，并在修改任何这些文件时自动重新启动worker。
未安装opcache 在开发映像中，因此PHP在每次工作程序启动时从磁盘读取源文件，而不是提供过时的缓存字节码。
APP_ENV=local 告诉Laravel框架在每次启动时检查配置和服务更改。

这些加在一起意味着对PHP文件或配置的任何更改都会在保存后立即生效——worker会在后台重新启动，下一个请求会用新代码处理。

前端资产 （CSS/JS）由Vite编译。在开发容器中，如果满足以下条件，资产将在首次启动时自动构建 public/build 不存在。要在更改后重建，请执行以下操作：

docker compose run --rm --no-deps planka-mcp npm run build

XDebug

默认情况下，XDebug已在开发映像中安装并启用。它在每次请求时都会连接到您的主机，不需要触发cookie或查询字符串。

设置	值
客户端主机	`host.docker.internal` （解析到你的Docker主机）
客户端端口	`9003`
服务器/IDE密钥	`planka_mcp`
启动模式	`start_with_request=yes` --自动触发每个请求

XDebug通过 XDEBUG_MODE 环境变量。默认值为 docker-compose.yml 是 debug。要禁用它，请执行以下操作：

XDEBUG_MODE=off PLANKA_URL=https://your-planka-instance.example.com docker compose up

暴风雪

打开 设置→ PHP → 服务器 并添加服务器：
- 姓名： planka_mcp
- 主持人： localhost
- 端口： 8080
- 调试器：XDebug
- 启用路径映射：将本地项目根映射到 /app
打开 设置→ PHP → Debug 并确认调试端口为 9003.
点击 开始监听PHP调试连接 按钮（工具栏中的电话图标）。
设置断点并发出请求——PhpStorm将自动在断点处暂停。

VS代码

安装 PHP 调试扩展，然后将此配置添加到 .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for XDebug (planka-mcp)",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/app": "${workspaceFolder}"
      }
    }
  ]
}

开始 收听XDebug 调试配置并发出触发调试器的请求。

重建后 `composer.json` 变化

docker compose up --build

入口点脚本运行 composer install 自动如果 vendor/autoload.php 不见了。

在本地构建生产Docker镜像

生产Docker构建包括一个Node.js阶段，该阶段通过Vite自动编译前端资产，不需要本地安装Node.js。

docker build -t planka-mcp:local .

工具	说明
`planka_manage_labels`	在电路板上创建、更新或删除标签
`planka_set_card_labels`	在卡片上添加或删除标签

使用说明

木板mcp

资源

系统

结构

板子

列表

卡

任务

自定义字段

用户

通知

网络钩子

工具

结构

项目

板子

列表

卡

标签

任务

评论

附件

用户

通知

自定义字段

网络钩子

活动

通知服务

需求

生产部署

使用Docker Compose（推荐）

使用 docker run

环境变量

Webhook订阅（可选）

认证

配置Claude代码

mcp.json

命令行界面

配置Claude桌面

健康检查

发展

需求

本地设置（无Docker）

运行测试

静态分析

Docker开发设置

XDebug

重建后 composer.json 变化

在本地构建生产Docker镜像

相关 MCP

思维工具服务器

APISIX MCP服务器

看板任务管理工具

模型上下文协议服务器

Markdown内容交付网络

思维工具服务器

使用 `docker run`

重建后 `composer.json` 变化