Zoom Whiteboard MCP 工具全解析:工具目录、Scope 映射与白板 ID 读取实战

原创2026-09-14 20:24:331,666 阅读
文章标签:人工智能AI 技能插件系统提示工程企业应用协同办公

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 是独立于主 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 为准:文档标题即点明"Current tools/list result",说明这份目录是对应时间点的真实探测结果。工具列表可能随 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 给出经过验证的读取流程:

  1. 使用带 Whiteboard 读 Scope 的 User OAuth 令牌;
  2. 调用 list_whiteboards 发现可访问的白板,确认正确的 whiteboard_id;
  3. 用该 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 秒快速检查:

  1. 令牌已导出?

    echo "${ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN:+set}"
    

    若为空,按 oauth-setup.md 完成用户 OAuth 授权与令牌交换后重新导出。

  2. 工具发现正常? 确认客户端能看到 list_whiteboards、get_a_whiteboard 等工具;如果客户端支持协议级检查,直接执行 tools/list 并以返回为权威。

  3. Scope 正确? 确认令牌包含 whiteboard:read:list_whiteboards 与 whiteboard:read:whiteboard;写操作另需 whiteboard:write:whiteboard。

  4. ID 选对? 读取目标白板时,从 URL 的 /wb/db/ 段提取 whiteboard_id,不要误用 /p/ 数字段。

  5. 错误排查就位? 若遇到 -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 工作流中稳定地完成白板的发现与读取。

登录后查看全文
knowledge-work-plugins