craaft

Craaft MCP Server

适用于 Craaft 的 Model Context Protocol 服务 - 让 AI 助手能够读取和写入你的看板。

部署为 HTTP 服务。每个请求都会通过调用方的 Authorization: Bearer 标头进行身份验证 - 可以使用 cra_* 个人访问令牌（与 Craaft REST API 使用的令牌相同），也可以使用通过下方连接器流程登录后签发的 cro_* OAuth 访问令牌。

Craaft 账户的双重验证不会影响这两种令牌。账户安全设置（密码、双重验证、API 密钥）只能在平台的浏览器中管理，因此没有任何工具会更改这些设置。

部署

cd mcp
gcloud run deploy craaft-mcp \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars CRAAFT_BASE_URL=https://craaft.io,MCP_PUBLIC_URL=https://ai.craaft.io/mcp

Cloud Run 会自动设置 PORT 环境变量。

从 Claude 连接（OAuth）

设置 MCP_PUBLIC_URL 后，该服务就是受 OAuth 2.1 保护的资源：无需手动复制令牌。

Craaft 已列入 Claude 目录：从那里连接，然后跳到第 3 步。或者将其添加为自定义连接器：

1. 在 Claude Desktop 或 claude.ai 中，前往 Settings > Connectors > Add custom connector。
2. 粘贴 https://ai.craaft.io/mcp。
3. 登录 Craaft，选择 Read and write 或 Read only，然后批准连接。

使用只读访问权限时，仅执行读取操作的工具（list_projects、get_board、 search_cards 等）可以正常工作，而所有会更改内容的工具都会失败，并提示 this token is read-only; this request needs a token with read and write access。只读创建的 cra_ 密钥也是如此。

你也可以仅连接 Chosen boards。此时，工具只能看到这些看板：找不到其他看板，且 list_projects 和 search_cards 会忽略它们。create_project、import_board、list_members、list_invitations 及其他成员工具都会失败，并提示 this token is limited to some boards; this request needs a token for all boards。如需更改应用的访问权限或看板范围，请重新连接并重新选择。

如需之后撤销访问权限，请前往 Craaft Settings > Connected apps。

配置（Claude Desktop，cra_ 令牌）

1. 登录 Craaft → Settings → API keys → 创建令牌
2. 添加到 ~/.config/claude/claude_desktop_config.json：

{
  "mcpServers": {
    "craaft": {
      "url": "https://craaft-mcp-xxxxx.a.run.app/mcp",
      "headers": {
        "Authorization": "Bearer cra_your_token_here"
      }
    }
  }
}

MCP 注册表

Craaft 已在官方 MCP 注册表中列出，名称为 io.craaft/mcp，其描述文件为 server.json。craaft.io 通过在 https://craaft.io/.well-known/mcp-registry-auth 提供公钥，证明其拥有 io.craaft 命名空间（平台仓库中的 internal/server/mcpregistry.go）。对应的私钥不在此仓库中。

如需发布更改，请提高 server.json 中的 version（已发布的版本无法更改或重新发布），然后：

PRIVATE_KEY="$(openssl pkey -in ~/.config/craaft/mcp-registry-key.pem -noout -text | grep -A3 'priv:' | tail -n +2 | tr -d ' :\n')"
mcp-publisher login http --domain craaft.io --private-key "$PRIVATE_KEY"
mcp-publisher publish

从注册表的版本发布页安装 mcp-publisher。

工具

工具	描述
list_projects	列出所有可访问的看板项目
get_board	获取看板的列和卡片（不包含描述）
get_card	按 ID 获取单张卡片，包含描述
get_card_detail	一次调用获取卡片及其评论、事件、清单和附件
search_cards	跨项目搜索卡片（描述为不超过 180 个字符的摘要）
create_card	在某列底部创建卡片，可选添加元数据（除非指定其他人，否则分配给你）
update_card	更新卡片标题、描述、列、位置、优先级、负责人、标签等
move_card	将卡片移至其他列或看板
delete_card	永久删除卡片
add_comment	向卡片添加评论（支持 @提及）
get_comments	列出卡片上的评论
get_focus	获取关注概览：到期卡片、需关注卡片和卫生状况计数
list_notifications	查看你的通知收件箱，按最新优先排序，并显示未读数量。传入 kind: mention 可列出提及你的通知，并包含项目、卡片和评论 ID
mark_notifications_read	按 ID、按卡片或全部标记通知为已读
get_me	获取已验证用户的个人资料
bulk_create_cards	在一个事务中创建最多 100 张卡片
bulk_update_cards	在一个事务中应用最多 100 项卡片部分更新
bulk_move_cards	将最多 100 张卡片批量移入某列，也可选择移至其他看板
rebalance_cards	在一个事务中重新排列整列卡片（位置为 1、2、3、……）
get_checklist	列出卡片的清单项
add_checklist_item	向卡片的清单末尾添加项目
update_checklist_item	勾选、取消勾选或重命名清单项
delete_checklist_item	删除清单项
get_card_activity	卡片的活动日志：列和看板移动、优先级和负责人变更
get_board_activity	看板活动动态，按最新优先排序：添加、移动、归档、删除的卡片，评论和列变更
get_hygiene	获取 get_focus 卫生状况计数（ghosts、stuck、mine_no_date）对应的卡片
list_attachments	列出卡片上的附件
list_board_files	搜索看板所有卡片上的文件，并显示每个文件所在的卡片
download_attachment	获取附件字节（文本内联显示，二进制以 base64 编码）
upload_attachment	从内联内容向卡片添加文件
delete_attachment	删除附件及其存储的字节
get_project	获取单个项目，包括列、计数和你的角色
create_project	创建看板，可选择使用模板（否则默认包含 To Do / In Progress / Done）
update_project	重命名、收藏、更改可见性、配色方案、背景、文字颜色或顶部栏按钮
delete_project	删除看板及其中所有内容
export_project	将看板导出为 JSON 或 CSV
preview_import	试运行导入：预览 Trello、Jira、Asana、CSV 或 craaft 导出文件将创建的看板
import_board	根据 Trello、Jira、Asana、CSV 或 craaft 导出文件创建新看板
list_board_templates	固定的看板模板目录（看板、冲刺、缺陷跟踪器等）
add_column	向看板添加列
update_column	重命名、更改颜色、重新排序或设置 WIP 限制
delete_column	删除空列
archive_column	归档已完成列中的所有卡片，并返回已归档的 ID
archive_card	归档单张卡片，但不删除
restore_card	将已归档的卡片恢复到原来的列和位置
list_archived_cards	列出看板的已归档卡片，按最新优先排序
list_webhooks	查看看板的出站 Webhook 订阅及事件目录
create_webhook	注册出站 Webhook（craaft 签名 / Slack / Discord）
update_webhook	暂停或恢复 Webhook，或更改其 URL、格式或事件筛选条件
delete_webhook	删除 Webhook 订阅
get_inbound_email	获取看板的邮件转卡片接收地址（如已配置）以及本月 AI 卡片用量
enable_inbound_email	启用邮件转卡片并生成接收地址
update_inbound_email	更改启用状态、目标列或轮换令牌
disable_inbound_email	关闭看板的邮件转卡片功能
list_members	查看工作区成员、角色和看板访问权限
update_member_role	更改成员的工作区角色
remove_member	从工作区移除成员
list_invitations	列出待处理的邀请
invite_member	通过电子邮件邀请成员，可选择授予看板访问权限
revoke_invitation	撤销待处理的邀请
list_board_members	查看哪些人可以查看看板，以及访问权限是显式授予还是隐式获得
grant_board_access	授予成员访问特定看板的权限，或更改其看板角色
revoke_board_access	撤销显式授予的看板访问权限
update_comment	编辑评论（仅作者可操作）
delete_comment	删除评论（作者或工作区所有者 / 管理员可操作）
set_card_follow	关注或取消关注卡片
list_tags	列出看板卡片上的不同标签，按顺序排列，包含已归档卡片
list_milestones	列出看板的里程碑，按到期时间从早到晚排列
add_milestone	添加里程碑（看板管理员可操作）
update_milestone	重命名、更改日期或标记为已达成
delete_milestone	删除里程碑
enable_sharing	启用只读公开分享，并返回令牌和 URL
disable_sharing	撤销公开链接
get_avatar	获取用户头像字节，或获取用于渲染占位符的提示
这 3 个 bulk_* 工具采用全有或全无的方式：只要有一个项目无效，整个批次就会回滚，并在错误中指出出错的索引，因此失败的调用绝不会导致看板只部分更新。它们不会发送通知邮件（活动事件和实时更新仍会触发），每次调用只消耗一个速率限制令牌，突发预算为 60 个令牌——因此应优先使用这些工具，而不是循环调用单卡片工具。

端点

路径	用途
POST /mcp	MCP Streamable HTTP 端点
GET /healthz	健康检查（返回 {"status":"ok"}）
GET /.well-known/oauth-protected-resource、GET /.well-known/oauth-protected-resource/mcp	RFC 9728 受保护资源元数据（仅在设置 MCP_PUBLIC_URL 时提供）

环境变量

变量	默认值	描述
PORT	8080	监听端口（Cloud Run 会自动设置此值）
CRAAFT_BASE_URL	https://craaft.io	上游 Craaft API URL
MCP_PUBLIC_URL	未设置（关闭 OAuth 元数据）	此服务自身的公开 /mcp URL，例如 https://ai.craaft.io/mcp。设置后，服务会提供 RFC 9728 受保护资源元数据，并对缺失或无效的令牌返回 401 挑战，以启动 OAuth 流程。无论是否设置，都接受 cra_ 个人访问令牌和 cro_ OAuth 访问令牌。该值必须与平台的 MCP_RESOURCE_URL 相同（比较前，两端都会将协议和主机名转换为小写，并去掉末尾的斜杠）。

附件

此服务在远程运行，因此无法读取调用方的文件系统： upload_attachment 需要直接传入内容（文本使用 content_text， 二进制使用 content_base64），而不是文件路径。

download_attachment 会将类似文本的内容类型作为可读文本返回， 其他内容则以 Base64 编码返回。附件最大为 25 MiB，但没有任何 对话适合直接内嵌这么大的内容，因此超过 max_bytes （默认为 256 KiB）的附件会被拒绝，并报告实际大小。文本会被截断， 而不是拒绝，因为截断后的文本仍可阅读；截断后的 Base64 则不可读， 因此超过限制的二进制内容会被完全跳过。

附件是付费功能。在 Free 工作区中，上传会返回 402， 错误中会指出当前套餐。请先检查项目的 canUploadAttachments—— 它反映的是看板所属工作区的套餐，而不是调用方的套餐。

导入

preview_import 和 import_board 接受相同的参数：filename、 内嵌文件内容（content_text 或 content_base64），以及可选的 source（trello、jira、asana、csv 或 craaft；省略时会自动检测）、 新看板的 name，以及将 Craaft 字段映射到标题的 CSV mapping。请先预览： 预览不会写入任何内容；对于 CSV，它会返回标题、建议的映射和示例行。 映射会替换建议，因此请发送所有所需字段。import_board 始终会创建新的私有看板， 并计入工作区的看板数量限制（达到上限时返回 402）。限制：5 MB、2,000 张卡片、 200 个列；不会导入附件。

已知的平台问题：先归档，再删除

archive_column 只会归档标记为 isDone 的列中的卡片； 对于其他列，它不会报错，而是返回 200，并附带 archived: 0（以及空的 ID 列表）—— 请检查数量。返回的 ID 可用于逐个对这些卡片调用 restore_card，撤销此次批量归档。

只有未归档的卡片会阻止 delete_column。已归档的卡片不会再阻止删除—— 它们会被重新分配到看板的第一列，然后删除继续进行，因此这些卡片会继续存在并保持归档状态。（此问题过去会导致删除失败：cards_project_column_fk 约束仍会检查已归档的行，因此删除会一直返回 409。此问题已在平台侧修复。）

归档和恢复

archive_card 会将卡片从看板移除，但不会删除卡片；卡片仍可搜索，并会显示在 list_archived_cards 中，直到 restore_card 将其放回归档时所在的确切列和位置。归档已归档的卡片，或恢复未归档的卡片，都会报错。list_archived_cards 使用与 get_board 相同的精简看板投影（不包含描述），另含 archivedAt，最多返回 200 行（按时间从新到旧排列）——较早归档的卡片仍可通过 search_cards 找到。

看板模板

所有调用方看到的 list_board_templates 都是相同的固定目录，不受套餐限制。将模板的 key 作为 create_project 的 template 参数传入，即可创建具有相应列布局的看板。无论是否使用模板，create_project 的响应都不会包含 columns；只有 get_project / get_board 会填充该字段。只有默认的 kanban 模板会沿用历史上的 todo / doing / done 列键，其他模板都会生成自己的列键，因此在新看板上创建卡片前，请先调用 get_project。

Webhook 和邮件转卡片（看板管理员，Pro）

这两种功能的限制方式相同：看板不可见 → 未找到；看板可见但你不是看板管理员 → 禁止访问；Free 工作区 → 返回 402，并将 "integrations" 指定为限制项。delete_webhook 和 disable_inbound_email 不受套餐限制，因此工作区在设置其中任一项后降级，仍可将其关闭。

每次读取（列表、创建、更新）时，都会完整返回 Webhook 订阅的 secret——创建后不会对其进行隐藏。它会通过 X-Craaft-Signature 标头为 craaft 格式的投递内容签名；slack 和 discord 投递内容则是未签名的聊天消息，仅由接收服务的密钥 URL 进行身份验证。update_webhook 的 subscription_id 参数是订阅的 id，不是响应中同时返回的工作区级 endpoint_id。

邮件转卡片会为每个看板生成一个收件地址（<token>@<inbound-domain>）。只有发件人是工作区成员且 SPF/DKIM 验证通过时，邮件才会转成卡片；其他邮件都会被静默丢弃，不会向发件人显示任何错误。update_inbound_email 的 rotate 标记会生成新令牌，并立即使旧地址失效——没有宽限期。

未公开的接口及原因

GET /projects/{id}/events 是看板的 SSE 实时流，不是活动日志——它是一个长期保持连接的 text/event-stream，不适合作为请求/响应工具。查看看板历史记录请使用 get_board_activity（/projects/{id}/activity），查看单张卡片的历史记录请使用 get_card_activity（/cards/{id}/events）。

此外未公开的还有：POST /projects/{id}/cards/rebalance（内部位置维护）、看板背景图片接口，以及无需身份验证的 /public/projects/{token} 读取接口——持有令牌的 Agent 只需使用 get_board。