Zoom Whiteboard MCP 工具全解析:工具目录、Scope 映射与白板 ID 读取实战
Zoom Whiteboard MCP 工具全解析:工具目录、Scope 映射与白板 ID 读取实战
本篇技术指南围绕 knowledge-work-plugins 仓库中 Zoom 插件自带的 Whiteboard MCP 工具面(tool surface)展开,系统梳理 tools/list 协议发现到的 8 个工具、受保护资源(protected-resource)元数据所声明的 Scope 家族,以及结合 list_whiteboards → get_a_whiteboard 读取工作流与 /wb/db/ ID 映射规则。读完你能够准确区分 Whiteboard MCP 与主 Zoom MCP 的能力边界,正确配置认证与 Scope,并安全地编写调用白板工具的实际脚本或 Agent 指令。
一、文档背景与证据来源
本文的主体事实来自仓库中的三份 Whiteboard MCP 专属文档:
- Whiteboard MCP 工具目录:本文的骨架,记录的是
https://mcp-us.zoom.us/mcp/whiteboard/streamable端点上当前tools/list的返回结果; - Whiteboard MCP 技能说明:端点、认证路径、必需 Scope、ID 映射与读取工作流;
- 认证与标识符参考:认证行为细节、运行时错误形态与响应形态说明。
需要强调:Whiteboard MCP 是独立于主 Zoom MCP 的单独 MCP 表面(surface)。主 Zoom MCP 服务器(mcp-us.zoom.us/mcp/zoom/streamable)暴露的是 search_meetings、get_meeting_assets、recordings_list、get_recording_resource 等会议与录制工具(见 主 Zoom MCP 工具参考),而白板相关请求必须路由到 Whiteboard MCP,这一点在主 zoom-mcp SKILL 中同样被明确强调。
二、Whiteboard MCP 端点与连接器配置
2.1 服务端点
Whiteboard MCP 提供两种传输方式(Whiteboard SKILL.md):
| 传输方式 | URL |
|---|---|
| Streamable HTTP(推荐) | https://mcp-us.zoom.us/mcp/whiteboard/streamable |
| SSE(备用) | https://mcp-us.zoom.us/mcp/whiteboard/sse |
2.2 连接器如何注入令牌
仓库中 .mcp.json 定义了三个并存的 MCP 服务器入口,Whiteboard 对应 zoom-whiteboard-mcp:
"zoom-whiteboard-mcp": {
"type": "http",
"url": "https://mcp-us.zoom.us/mcp/whiteboard/streamable",
"headers": {
"Authorization": "Bearer ${ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN}"
}
}
从配置可以看出,插件通过 Authorization: Bearer 头携带访问令牌,令牌值来自环境变量 ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN(与主 Zoom MCP 的 ZOOM_MCP_ACCESS_TOKEN、Docs MCP 的 ZOOM_DOCS_MCP_ACCESS_TOKEN 相互独立)。因此启用前必须:
export ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN="your_whiteboard_user_oauth_token"
随后重启 Claude 或重新启用插件,让连接器以新令牌重启 MCP 服务器(参考 RUNBOOK 预检清单 中的令牌检查步骤)。
三、工具目录:8 个 Whiteboard MCP 工具详解
文档 tools.md 记录的是 Whiteboard MCP 表面当前 tools/list 的实际结果。工具按用途可划分为两类:读取类(list_whiteboards、get_a_whiteboard)与创建/更新类(其余 6 个以 create_a_whiteboard_*、update_a_whiteboard_* 命名的工具)。
| 工具 | 用途 | 指南覆盖情况 |
|---|---|---|
create_a_whiteboard_for_brainstorming |
根据头脑风暴输入(问题、想法、下一步行动)创建白板 | 在 Whiteboard MCP 表面可用;使用前需校验请求 schema |
list_whiteboards |
列出当前用户或管理员上下文可访问的白板 | 由本指南的读取工作流覆盖 |
create_a_whiteboard |
创建白板 | 在 Whiteboard MCP 表面可用;使用前需校验请求 schema |
get_a_whiteboard |
通过 whiteboard_id 获取白板 |
由本指南的读取工作流覆盖 |
create_a_whiteboard_by_script |
使用脚本化内容或结构化输入创建白板 | 在 Whiteboard MCP 表面可用;使用前需校验请求 schema |
update_a_whiteboard_metadata |
更新白板元数据 | 在 Whiteboard MCP 表面可用;使用前需校验请求 schema |
create_a_whiteboard_for_meeting_summary |
从会议纪要(meeting-summary)风格输入生成白板 | 在 Whiteboard MCP 表面可用;使用前需校验请求 schema |
create_a_whiteboard_for_strategy_analysis |
为策略分析内容生成白板 | 在 Whiteboard MCP 表面可用;使用前需校验请求 schema |
3.1 工具命名的语义解读
从工具命名与用途描述可以推断该工具面的设计意图:
- 按场景封装的创建工具:
create_a_whiteboard_for_brainstorming、create_a_whiteboard_for_meeting_summary、create_a_whiteboard_for_strategy_analysis分别对应"头脑风暴""会议纪要""策略分析"三类高频白板场景,说明 Whiteboard MCP 面向的是知识工作者的结构化输入生成,而非通用的像素级画布操作; - 通用创建与脚本化创建:
create_a_whiteboard是基础创建入口,create_a_whiteboard_by_script则接受脚本化/结构化内容,适合程序化批量生成; - 元数据更新:
update_a_whiteboard_metadata用于更新白板元数据,属于写能力; - 读取两个工具:
list_whiteboards(列举)与get_a_whiteboard(按 ID 读取)构成完整的读取链路,也是本指南读取工作流的两个核心工具。
3.2 工具面使用要点
- 以
tools/list为准:文档标题即点明"Currenttools/listresult",说明这份目录是对应时间点的真实探测结果。工具列表可能随 Zoom 服务端演进变化,需要确认当前工具时,应重新执行tools/list并以其实时返回为准,这一原则与主 Zoom MCP 的发现机制一致(见 zoom-mcp SKILL 的快速开始)。 - 客户端命名空间:部分 MCP 客户端会在 UI 中给服务器工具加命名空间前缀(例如
zoom-whiteboard-mcp:list_whiteboards)。以tools.md中记录的原始工具名(raw tool names)为准。 - 创建/更新类工具需先校验 schema:对于
create_a_whiteboard_for_brainstorming、create_a_whiteboard、create_a_whiteboard_by_script、update_a_whiteboard_metadata、create_a_whiteboard_for_meeting_summary、create_a_whiteboard_for_strategy_analysis这 6 个写能力工具,文档明确提示"validate request schema before use"——调用前务必通过tools/list确认每个参数的名称、类型与必填性,避免按猜测传参。 - 主 Zoom MCP 不提供白板创建:主 Zoom MCP 当前工具面不暴露确定性的会议/白板 CRUD 工具(zoom-mcp SKILL 关键说明),因此白板创建与读取都应走 Whiteboard MCP。
四、受保护资源与 Scope 家族
Whiteboard MCP 网关在受保护资源(protected-resource)元数据中声明了以下 Scope 家族(tools.md):
whiteboard:write:whiteboard—— 白板写权限,对应创建/更新类工具的写能力;whiteboard:read:list_whiteboards—— 白板列举读权限,对应list_whiteboards;whiteboard:read:whiteboard—— 单个白板读取权限,对应get_a_whiteboard。
4.1 认证路径选择:User OAuth 优先
根据 Whiteboard SKILL.md 与 authentication-and-identifiers.md 的验证结论:
- User OAuth(带 Whiteboard 相关 Scope) 是经过验证可用的读取路径,
list_whiteboards与get_a_whiteboard均可用用户 OAuth 令牌执行; - S2S(Server-to-Server)OAuth 可以连到 Whiteboard MCP 网关并完成
tools/list协议发现,但工具执行必须针对你的应用与 Whiteboard Scope 单独验证,不可默认可用; - 实操规则:除非已经证明你的 S2S 应用可以签发并执行带所需 Whiteboard Scope 的调用,否则一律先用 User OAuth。
User OAuth 模式下必需的最小 Scope 集合为:
whiteboard:read:list_whiteboards
whiteboard:read:whiteboard
4.2 缺失 Scope 的典型错误形态
文档记录了一个 S2S 令牌缺少预期 Scope 时的运行时错误示例:
Invalid access token, does not contain scopes:[whiteboard:read:admin,whiteboard:read]
这个错误形态(-32001 Invalid access token)与主 Zoom MCP 的 Scope 错误同族,含义是"令牌有效但缺少所调用工具要求的精确 Scope"。遇到此类错误时:核对应用已勾选的 Scope、重新签发用户令牌并更新 ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN,再重启客户端让连接器加载新令牌(对齐 common-errors.md 的修复路径)。
4.3 Scope 只解决"授权",不解决"数据是否可用"
与主 Zoom MCP 类似,Whiteboard 的读取结果质量取决于 Zoom 侧数据本身:AI Companion 的 Smart Recording、Meeting Summary 等功能是否开启,决定了会议纪要类白板输入是否有内容可依。这些功能设置是数据前置条件,不能替代上述 OAuth Scope(参见 oauth-setup.md 的 AI Companion 说明)。
五、读取工作流与 Whiteboard ID 映射
5.1 三步读取工作流
Whiteboard SKILL.md 给出经过验证的读取流程:
- 使用带 Whiteboard 读 Scope 的 User OAuth 令牌;
- 调用
list_whiteboards发现可访问的白板,确认正确的whiteboard_id; - 用该
whiteboard_id调用get_a_whiteboard读取白板内容。
list_whiteboards
→ 从返回结果中挑选目标 whiteboard_id
get_a_whiteboard
whiteboard_id: "6iktP8hJT3e5qaCuwFuAGg"
5.2 关键陷阱:/wb/db/ 之后的才是 whiteboard_id
Whiteboard 的浏览器 URL 同时包含两段标识符,文档明确要求使用 /wb/db/ 之后的 URL 段,而不是 /p/ 之后的数字段:
https://us05whiteboard.zoom.us/wb/db/6iktP8hJT3e5qaCuwFuAGg/p/180968285929472
^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
whiteboard_id page/subresource id
- 正确的 MCP
whiteboard_id:6iktP8hJT3e5qaCuwFuAGg; /p/...之后的数字(如180968285929472)是页面/子资源 ID,不是 Whiteboard MCP 的标识符。
5.3 响应形态:不要假设"单对象返回"
一个值得注意的实测结论(见 authentication-and-identifiers.md):get_a_whiteboard 实际返回的是列表风格(list-style)的载荷,包含匹配到的白板,而不是明显的单对象载荷。即使工具名暗示"get 单个对象",解析时也应以线上服务器实际返回的响应结构为准,先探测再编写解析代码。
六、调用前的预检清单
结合 RUNBOOK.md 的预检思想,为 Whiteboard MCP 做一次 60 秒快速检查:
-
令牌已导出?
echo "${ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN:+set}"若为空,按 oauth-setup.md 完成用户 OAuth 授权与令牌交换后重新导出。
-
工具发现正常? 确认客户端能看到
list_whiteboards、get_a_whiteboard等工具;如果客户端支持协议级检查,直接执行tools/list并以返回为权威。 -
Scope 正确? 确认令牌包含
whiteboard:read:list_whiteboards与whiteboard:read:whiteboard;写操作另需whiteboard:write:whiteboard。 -
ID 选对? 读取目标白板时,从 URL 的
/wb/db/段提取whiteboard_id,不要误用/p/数字段。 -
错误排查就位? 若遇到
-32001 Invalid access token,按"刷新令牌 → 核对 Scope → 更新环境变量 → 重启客户端"的顺序处理;若遇到-32602 Can not found tool,先确认请求发到了 Whiteboard 端点(mcp-us.zoom.us/mcp/whiteboard/streamable)而不是主 Zoom MCP 端点。
七、与其他 MCP 表面的边界
最后澄清一个容易混淆的边界(依据 zoom-mcp SKILL 关键说明):
- 会议搜索/资产/录制 → 主 Zoom MCP(
https://mcp-us.zoom.us/mcp/zoom/streamable),工具为search_meetings、get_meeting_assets、recordings_list、get_recording_resource; - Zoom Docs → 专用
zoom-docs-mcp(https://mcp.zoom.us/mcp/docs/streamable),工具为create_file_with_content、get_file_content; - 白板 → 本文主题 Whiteboard MCP(
https://mcp-us.zoom.us/mcp/whiteboard/streamable),工具为上述 8 个,认证、Scope 与 ID 规则均独立。
Whiteboard MCP 虽然是独立表面,但其"以 tools/list 为权威、以 User OAuth 为验证路径、以精确 Scope 为执行前提"的原则,与整个 Zoom MCP 插件家族保持一致。将本文的工具目录、Scope 映射与 ID 规则组合使用,即可在 Agent 工作流中稳定地完成白板的发现与读取。