Zoom Mcp

Zoom MCP

Guidance for the bundled Zoom MCP connector in this Claude plugin. Prefer design-mcp-workflow or setup-zoom-mcp first, then route here for tool-surface details, auth expectations, and MCP-specific constraints.

Zoom MCP Server

This plugin bundles Zoom's hosted MCP server at mcp-us.zoom.us for AI-agent access to:

• semantic meeting search
• meeting-linked asset retrieval
• recording resource retrieval

Zoom Docs are exposed through a separate bundled server:

• zoom-docs-mcp at mcp.zoom.us
• purpose-built for Zoom Docs creation and retrieval

Current tool names from the main Zoom MCP server:

• get_meeting_assets
• search_meetings
• get_recording_resource
• recordings_list

Some MCP clients namespace server tools in the UI, for example zoom-mcp:recordings_list. Treat the raw tool names above as authoritative.

Zoom Docs-specific MCP work should use the dedicated zoom-docs-mcp server.

Whiteboard-specific MCP work is covered by the dedicated skill whiteboard/SKILL.md.

Quick Start

1. Export the token expected by the bundled connector:

export ZOOM_MCP_ACCESS_TOKEN="your_zoom_user_oauth_access_token"

2. Enable or restart the plugin so Claude restarts the bundled MCP server definition.

3. Verify discovery:

• Confirm the client can see recordings_list, search_meetings, get_meeting_assets,

and get_recording_resource.

• If the client exposes raw protocol inspection, tools/list is the authoritative discovery source.
• The current catalog is documented in references/tools.md.

4. Run the first useful call:

recordings_list
  userId: "me"
  from: "2026-03-01"
  to: "2026-03-06"
  page_size: 10

Critical Notes

1. User OAuth is the documented execution path

Use a General app with user-level OAuth as the execution path for Zoom MCP tool use in this plugin. Do not rely on Server-to-Server OAuth as a supported MCP auth model here.

2. Zoom MCP uses MCP-specific granular scopes

The Zoom MCP scope set is not the same as the older broad REST scopes. The key scopes for the main Zoom MCP server are:

• ai_companion:read:search — Search across Zoom Meeting, Zoom Chat, and Zoom Doc, returning the most relevant results based on the query
• meeting:read:search — Search and view meetings
• meeting:read:assets — View a meeting's assets
• cloud_recording:read:list_user_recordings — Lists all cloud recordings for a user.
• cloud_recording:read:content — read recording content scope
• docs:write:import — Create a new file by import
• docs:read:export — Read file content in Markdown format

For Zoom Docs MCP specifically, the official docs page shows these granular scopes for the documented tools:

• docs:write:import — Create a new file by import
• docs:read:export — Read file content in Markdown format

3. AI Companion features are feature prerequisites, not scope substitutes

Semantic meeting search, meeting assets, and recording-content retrieval depend on account features such as Smart Recording and Meeting Summary for useful results. These feature settings do not replace the required OAuth scopes.

4. Whiteboard is a separate MCP surface

The Zoom MCP endpoint and the Whiteboard MCP endpoint are separate. Route Whiteboard-specific requests to whiteboard/SKILL.md.

5. Use REST for deterministic meeting CRUD

The current Zoom MCP tool surface does not expose deterministic meeting create, update, or delete tools. If the user needs explicit meeting CRUD operations, route to ../rest-api/SKILL.md.

Server Endpoints

Dedicated Docs MCP server:

Dedicated Whiteboard MCP skill:

• whiteboard/SKILL.md

Search and Retrieval Model

search_meetings uses AI Companion retrieval rather than a plain metadata filter. In this use the live MCP server as authoritative for response schema and scope behavior.

Two result families matter most:

• Recap-oriented results: AI summary, meeting-linked documents, recordings, and related assets
• Recording-oriented results: cloud recording references and transcript-capable resources

Use examples/transcript-retrieval.md for the main retrieval workflow.

Tool Catalog

\* Required parameter

Full parameter and output guidance: references/tools.md

Key Workflows

Search meeting content, then retrieve assets:

search_meetings
  q: "Q4 planning discussion"
  from: "2026-03-01"
  to: "2026-03-06"
→ choose a returned meeting
→ get_meeting_assets  meetingId: "MEETING_ID_OR_UUID"

List recordings, then retrieve recording resources:

recordings_list
  userId: "me"
  from: "2026-03-01"
  to: "2026-03-06"
→ choose a recording target
→ get_recording_resource  meetingId: "MEETING_UUID_OR_RECORDING_ID"

Create or fetch a Zoom Doc:

• use the dedicated zoom-docs-mcp server rather than the main zoom-mcp server
• official documented tools on the Zoom Docs MCP page are:
• create_file_with_content
• get_file_content

Error Reference

Full error reference: references/error-codes.md

Documentation

Concepts

• concepts/mcp-architecture.md — MCP protocol, hosted endpoints, discovery, and capability model
• concepts/oauth-setup.md — OAuth app creation, MCP-specific scopes, AI Companion prerequisites, token lifecycle

Examples

• examples/transcript-retrieval.md — Search/assets and recording-resource workflows
• examples/create-zoom-doc.md — Verified Zoom Docs creation flow
• examples/search-and-act.md — Search, inspect assets, and hand off CRUD work to REST when needed
• examples/meeting-lifecycle.md — Why meeting CRUD belongs in REST, plus the MCP-to-REST handoff pattern

References

• references/tools.md — Current Zoom MCP tool reference
• references/error-codes.md — MCP and Zoom API errors with fixes
• whiteboard/SKILL.md — Dedicated Whiteboard MCP skill

Troubleshooting

• troubleshooting/common-errors.md — Scope failures, endpoint mixups, search/recording issues

Operations

• RUNBOOK.md — 5-minute preflight and debugging checklist

Related Skills

• zoom-rest-api — Deterministic REST API access, including meeting CRUD
• zoom-oauth — OAuth implementation patterns
• zoom-webhooks — Event-driven recording and meeting workflows
• zoom-rtms — Live media and transcript streams during active meetings

MCP Architecture — Zoom MCP Server

What is MCP?

Model Context Protocol (MCP) standardizes how AI systems connect to external tools and data sources. Zoom exposes hosted MCP surfaces that clients can discover and call over MCP.

Hosted Zoom MCP Surfaces

Zoom MCP

Whiteboard MCP

Whiteboard MCP is covered by the dedicated skill ../whiteboard/SKILL.md.

Discovery Model

Do not hardcode tool counts in client logic.

Use the MCP protocol tools/list response as the current source of truth for:

• tool names
• descriptions
• parameter schemas
• newly added or removed tools

Current Capability Shape

The current Zoom MCP surface is centered on:

• semantic meeting search
• meeting asset retrieval
• recording resource retrieval
• Zoom Docs creation from Markdown

If the task requires deterministic meeting CRUD, use the REST API skill instead of assuming those operations exist on the current Zoom MCP surface.

Authentication Model

User OAuth is the primary documented path. Use user OAuth as the expected auth model for the bundled Zoom MCP servers in this plugin.

Protected Resource Metadata

The hosted MCP surfaces advertise supported scopes through OAuth protected-resource metadata. Zoom MCP protected-resource metadata currently exposes:

• ai_companion:read:search
• meeting:read:assets
• meeting:read:search
• cloud_recording:read:content
• cloud_recording:read:list_user_recordings
• docs:write:import
• docs:read:export

Whiteboard MCP protected-resource metadata currently exposes:

• whiteboard:write:whiteboard
• whiteboard:read:list_whiteboards
• whiteboard:read:whiteboard

Retrieval Model

search_meetings is not just a title filter. It is a semantic retrieval path over meeting content, recap-linked assets, and recording-linked artifacts.

Useful result families:

• recap-oriented results with AI summaries and linked assets
• recording-oriented results for post-meeting content retrieval

When writing parsers, validate the live response shape from the server rather than relying on older example field names.

Feature Prerequisites

AI Companion features such as Smart Recording and Meeting Summary are feature prerequisites for useful semantic retrieval and recap-linked content. They do not replace the required OAuth scopes.

Error Layering

Failures can happen at two layers:

• MCP protocol layer (-32001, -32602, -32603)
• underlying Zoom API-style permission/resource failures surfaced through the MCP response

See ../references/error-codes.md.

OAuth Setup — Zoom MCP Server

Overview

The documented path for Zoom MCP is a General app using user-level OAuth. Each user authorizes with their own Zoom account, and the resulting bearer token is passed by the bundled connector in `.mcp.json`.

Step 1: Create a General App with User-Level OAuth

1. Go to marketplace.zoom.us → Develop → Build App. 2. Create a General app. 3. Configure the app for user-level OAuth for the per-user MCP path. 4. Set a redirect URL for your client or local test environment. 5. Note the client ID and client secret.

If You Do Not Already Have a Redirect Endpoint

For development, two pragmatic options are:

Option 0: `localhost` and manually copy the code

Example:

http://localhost:3000/oauth/zoom/callback

If the local app does not actually handle the callback yet, the browser may show a failed page load. You can still copy the code and state values from the browser URL and paste them into Claude or your terminal flow so the token exchange can continue manually.

Pros:

• no tunnel and no third-party capture service
• fastest setup if you only need the authorization code once
• keeps the authorization code on your machine

Cons:

• manual copy/paste step every time
• no automatic code exchange or refresh flow
• less convenient if you repeat the auth flow often

Option 1: `ngrok` in front of a local callback server

Example:

Local app: http://localhost:3000/oauth/zoom/callback
Public redirect URL: https://your-subdomain.ngrok.app/oauth/zoom/callback

Pros:

• best match for the real OAuth flow because your own app receives the callback directly
• easy to inspect requests locally while keeping your app logic in one place
• useful if you also need to exchange the code for tokens automatically

Cons:

• requires running a local server plus the tunnel
• slightly more setup than a capture-only endpoint
• you are exposing a local service to the internet, so keep the callback narrow and temporary

Option 2: `webhook.site` for one-off callback capture

Example:

https://webhook.site/your-token

Pros:

• fastest path when you just need to capture the authorization redirect once
• no local server required
• easy to inspect the query string and copy out code and state

Cons:

• not a full OAuth app backend; you still need to exchange the code for tokens yourself
• weaker fit for repeated development flows and team usage
• the authorization code is sensitive, so only use this for short-lived development testing and

avoid shared or long-lived capture URLs

Practical recommendation:

• use plain localhost if you only need a one-off auth code and are fine copying it manually
• use ngrok if you are building a real integration or expect to repeat the flow
• use webhook.site only for quick one-off testing when you do not yet have a callback handler

Step 2: Configure Zoom MCP Scopes

Add the MCP-specific granular scopes required by the tools you want to use.

Minimum recommendation for the main Zoom MCP connector:

• use a General app
• use user-level OAuth
• include the 7 main MCP scopes above on the same app

For the dedicated Zoom Docs MCP connector:

• add docs:write:import if you want Docs creation
• add docs:read:export if you want Docs retrieval
• export the resulting token as ZOOM_DOCS_MCP_ACCESS_TOKEN

Whiteboard MCP uses a separate scope set. See ../whiteboard/SKILL.md.

Step 3: Authorize and Exchange for Tokens

1. Construct the authorization URL:

   https://zoom.us/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI

2. Sign in as the Zoom user who should authorize the app and approve the requested scopes. 3. Copy the code from the redirect URL. 4. Exchange the code for tokens:

   curl -X POST https://zoom.us/oauth/token \
     -u "CLIENT_ID:CLIENT_SECRET" \
     -d "grant_type=authorization_code&code=CODE&redirect_uri=REDIRECT_URI"

5. Store the returned access_token and refresh_token.

Treat the refresh token as single-use:

• every successful refresh can return a new refresh token
• persist the newly returned refresh token atomically with the new access token
• stop using the old refresh token after a successful refresh
• avoid concurrent refresh requests against the same stored token

If you used webhook.site, the callback will arrive as a captured request and the code parameter will be in the query string. Exchange it immediately and do not keep using the same capture URL longer than necessary.

Step 4: Enable AI Companion Features

Smart Recording and Meeting Summary are feature prerequisites for useful semantic meeting search, meeting assets, and transcript-rich recording content.

In the Zoom web portal: 1. Go to Admin → Account Management → Account Settings → AI Companion. 2. Enable Smart Recording. 3. Enable Meeting Summary.

Important:

• these settings do not replace the OAuth scopes above
• they affect whether useful recap and transcript content exists for MCP retrieval

Step 5: Provide the Token to the Bundled MCP Connector

Export the token environment variable used by this plugin:

export ZOOM_MCP_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
export ZOOM_DOCS_MCP_ACCESS_TOKEN="YOUR_DOCS_ACCESS_TOKEN"

Verification:

• restart Claude Code or re-enable the plugin so the bundled MCP server restarts with the token
• confirm the client can see recordings_list, search_meetings, get_meeting_assets,

and get_recording_resource

• for the dedicated Docs server, confirm the client can see create_file_with_content

and get_file_content

• if your client exposes protocol inspection, use tools/list as the authority for the live catalog
• run a simple tool such as recordings_list to verify the token has the correct MCP scopes

Token Lifecycle

Refresh exchange:

curl -X POST https://zoom.us/oauth/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN"

After a successful refresh:

• replace the stored access token
• replace the stored refresh token
• treat the previously used refresh token as spent
• restart Claude Code or re-enable the plugin if you are injecting tokens through env vars

Environment Variables

ZOOM_CLIENT_ID=your_client_id
ZOOM_CLIENT_SECRET=your_client_secret
ZOOM_MCP_ACCESS_TOKEN=your_access_token
ZOOM_DOCS_MCP_ACCESS_TOKEN=your_docs_access_token
ZOOM_REFRESH_TOKEN=your_refresh_token

See also: ../../oauth/SKILL.md

Create a Zoom Doc

Use the dedicated zoom-docs-mcp server for Zoom Docs creation and retrieval. The official documented docs tools are create_file_with_content and get_file_content.

Required Scope

• docs:write:import

Basic Flow

Step 1: Gather the source content

If the source is meeting content, first use the current Zoom MCP retrieval tools.

search_meetings
  q: "Q1 planning"
  from: "2026-03-01"
  to: "2026-03-06"

get_meeting_assets
  meetingId: "MEETING_ID_OR_UUID"

Step 2: Create the Zoom Doc

create_file_with_content
  file_name: "Q1 Planning — Action Items"
  content: "# Action Items\n\n- Owner: ..."

Optional parameter:

• parent_id to place the document under a specific folder or parent object

Verified Result Shape

Successful calls return:

• file_id
• file_link

Expect clients to expose at least the created file ID, and in practice often a direct Docs link. Always parse the actual response you receive from the MCP client.

Example Prompts

• "Create a Zoom Doc with the action items from today's planning meeting."
• "Search for the product review and publish the recap as a Zoom Doc."
• "Turn these Markdown notes into a Zoom Doc."

Meeting Lifecycle — Use REST for CRUD

The current Zoom MCP surface does not expose deterministic meeting create, update, list, or delete tools.

If the user needs meeting lifecycle management, route to the REST API skill:

• ../../rest-api/SKILL.md

What Zoom MCP Is Good For

Use Zoom MCP for:

• semantic search across meetings
• retrieval of meeting-linked assets
• recording-resource retrieval
• Zoom Docs creation from Markdown

What To Use Instead for CRUD

Use the REST API for:

• create a meeting
• reschedule or update a meeting
• list scheduled meetings deterministically
• delete a meeting or occurrence

Hybrid Pattern

Use MCP first when the user starts with meeting content or recap intent, then hand off to REST only if the next action becomes a deterministic resource-management step.

Example:

1. search_meetings
   q: "client onboarding"
   from: "2026-03-01"
   to: "2026-03-06"

2. get_meeting_assets
   meetingId: "MEETING_ID_OR_UUID"

3. If the user then wants to reschedule or delete the meeting,
   route to zoom-rest-api and perform the CRUD operation there.

Example Prompts That Should Route to REST

• "Create a 45-minute design review for next Tuesday."
• "Move my Q1 planning meeting to Friday at 3pm Pacific."
• "Delete the team sync meeting scheduled for March 10th."
• "Show me all my scheduled meetings for this week."

Search and Act — Zoom MCP Patterns

Patterns for finding meetings and taking action using the current Zoom MCP tool surface.

Search by Topic or Time Range

search_meetings
  q: "budget review"
  from: "2026-03-01"
  to: "2026-03-06"
  page_size: 10

Use this when the user starts from what was discussed rather than from a known meeting ID.

Search Then Inspect Assets

Step 1:
search_meetings
  q: "product roadmap"
  from: "2026-03-01"
  to: "2026-03-06"

Step 2:
get_meeting_assets
  meetingId: "MEETING_ID_OR_UUID"

This is the main MCP pattern for retrieving summaries, recording references, linked docs, and other meeting-related assets.

Search Then Inspect Recording Resources

Step 1:
search_meetings
  q: "all hands"
  from: "2026-03-01"
  to: "2026-03-06"

Step 2:
get_recording_resource
  meetingId: "MEETING_ID_OR_UUID"

Use this when the user needs transcript-capable or playback-oriented resources after they have identified the target meeting.

Search Then Create a Zoom Doc

Step 1:
search_meetings
  q: "Q1 planning"

Step 2:
get_meeting_assets
  meetingId: "MEETING_ID_OR_UUID"

Step 3:
switch to the dedicated zoom-docs-mcp server

Step 4:
create_file_with_content
  file_name: "Q1 Planning Summary"
  content: "# Decisions\n\n- ..."

When to Hand Off to REST

If the user asks for deterministic operations such as:

• create a meeting
• reschedule a meeting
• update meeting settings
• delete a meeting

route to ../../rest-api/SKILL.md instead of assuming the current Zoom MCP surface exposes meeting CRUD.

Example Prompts

• "Find meetings about the product launch in February and summarize them."
• "Look up last week's all-hands and pull the recording resources."
• "Search for Q1 planning discussions and create a Zoom Doc from the recap."
• "I need to reschedule a meeting" → hand off to the REST API skill.

Transcript and Summary Retrieval

Use the Zoom MCP server when the goal is to search meeting content, retrieve meeting-linked assets, or fetch recording-oriented resources after a meeting.

Path 1: Semantic Search and Meeting Assets

Use this path when the user starts from content, topic, or time range.

Prerequisites

• meeting:read:search
• meeting:read:assets
• AI Companion features such as Smart Recording and Meeting Summary enabled for useful recap data

Step 1: Search meetings

search_meetings
  q: "Q4 budget discussion"
  from: "2026-03-01"
  to: "2026-03-06"
  page_size: 20

Step 2: Choose a meeting and retrieve assets

get_meeting_assets
  meetingId: "MEETING_ID_OR_UUID"

Expect the result to contain a meeting-linked asset bundle. In practice, this can include:

• AI summary or recap-linked content
• recording references
• linked documents
• whiteboard links

Do not hardcode exact field names without checking a current live response.

Path 2: Recording-Oriented Retrieval

Use this path when the user needs transcript-capable resources, recording playback resources, or recording lookup by user/date range.

Prerequisites

• cloud_recording:read:list_user_recordings
• cloud_recording:read:content

Step 1: List recordings

recordings_list
  userId: "me"
  from: "2026-03-01"
  to: "2026-03-06"
  page_size: 50

Step 2: Retrieve recording resources

get_recording_resource
  meetingId: "MEETING_UUID_OR_RECORDING_ID"

Use this when the user needs recording-oriented data such as:

• transcript timelines
• summary segments
• next-step segments
• playback URLs
• recording metadata

Choosing Between the Paths

Direct Downloads

If a returned recording resource includes a direct URL, fetch it with the same bearer token. The URL is not public by default.

Troubleshooting

`search_meetings` fails with missing scope:

• add meeting:read:search

`get_meeting_assets` fails with missing scope:

• add meeting:read:assets

`recordings_list` fails with missing scope:

• add cloud_recording:read:list_user_recordings

`get_recording_resource` fails with missing scope:

• add cloud_recording:read:content

Search results are sparse or low quality:

• enable Smart Recording and Meeting Summary
• widen the date window
• fall back to recordings_list if the user is really asking for post-meeting recording content

Error Codes — Zoom MCP Server

Errors can surface from the MCP protocol layer or from the underlying Zoom API-style behavior behind a tool call.

MCP Protocol Errors

Exact Scope Errors Observed in Testing

Recording and Transcript Failures

Upstream API Validation Errors

Some tool calls can succeed at the MCP protocol layer but surface a downstream Zoom API validation error in the result payload.

Common downstream validation response:

Whiteboard Server Split

The Zoom MCP server (mcp-us.zoom.us/mcp/zoom/streamable), the Zoom Docs MCP server (mcp.zoom.us/mcp/docs/streamable), and the Whiteboard MCP server (mcp-us.zoom.us/mcp/whiteboard/streamable) are separate surfaces.

Use the dedicated Whiteboard MCP skill for Whiteboard-specific auth, scopes, and identifier mapping:

• ../whiteboard/SKILL.md

Debugging Checklist

1. Confirm the client can discover the current MCP tool list through tools/list. 2. Confirm the bearer token is fresh. 3. Verify the exact MCP-specific scopes, not just adjacent REST scopes. 4. Re-discover the target meeting or recording instead of reusing guessed IDs.

Tool Reference — Zoom MCP Servers

Tools available on the bundled Zoom MCP servers. Treat the raw server tool names as authoritative. Some MCP clients namespace them in the UI, for example zoom-mcp:recordings_list or zoom-docs-mcp:create_file_with_content.

This reference is based on the current documented and observed tool surfaces of:

• https://mcp-us.zoom.us/mcp/zoom/streamable
• https://mcp.zoom.us/mcp/docs/streamable

Treat the live MCP protocol tools/list response as the authoritative source for the current tool list and schemas.

Main Zoom MCP Server Tools

The main Zoom MCP server exposes these tools:

• get_meeting_assets
• search_meetings
• get_recording_resource
• recordings_list

The server did not expose older inferred tool names such as list_meetings, get_meeting, create_meeting, get_user_profile, list_available_tools, or get_tool_details in that probe.

Supported Scope Families Advertised by Zoom MCP

Protected-resource metadata for the main Zoom MCP server advertised these scope families:

• ai_companion:read:search
• meeting:read:assets
• meeting:read:search
• cloud_recording:read:content
• cloud_recording:read:list_user_recordings
• docs:write:import
• docs:read:export

Zoom Docs MCP Server Tools

The dedicated Zoom Docs MCP server exposes these documented tools:

• create_file_with_content
• get_file_content

create_file_with_content

Create a Zoom Docs document from Markdown content.

Verified scope: docs:write:import

Successful calls return:

• file_id
• file_link

get_file_content

Retrieve a Zoom Docs document in Markdown format.

Verified scope: docs:read:export

Meeting Discovery and Assets

search_meetings

Read-only search tool for semantic meeting discovery.

Verified scope: meeting:read:search

get_meeting_assets

Read-only meeting asset hub. Retrieves meeting summary, recording, whiteboards, Zoom Docs, and related artifacts for a specific meeting.

Verified scope: meeting:read:assets

Important live-schema note:

• UUID-style values may require double encoding when they contain / or //.
• The tool description strongly prefers explicit user selection when choosing a meeting from search results.

Recordings

recordings_list

List cloud recordings for a user.

Verified scope: cloud_recording:read:list_user_recordings

get_recording_resource

Retrieve recording-oriented assets for a specific meeting, including transcript-like, summary-like, and playback-oriented resources.

Verified scope: cloud_recording:read:content

Output shape from live schema includes resource families such as:

• transcript timelines
• summaries
• next steps
• play URLs

Discovery Notes

• Discovery happens through MCP protocol tools/list, not through a dedicated Zoom utility tool.
• Re-run tools/list whenever you need to confirm whether the current tool list has changed.
• Do not rely on older examples that use query, startDate, endDate, or pageSize; the current live schema uses q, from, to, and page_size.
• Do not rely on older examples that route Docs creation through the main zoom-mcp server; Zoom Docs now have a dedicated zoom-docs-mcp server in this plugin.

zoom-mcp RUNBOOK — 5-Minute Preflight

Quick diagnostic checklist before using the Zoom MCP server.

Preflight Checklist

1. Token exported for the bundled connector?

echo "${ZOOM_MCP_ACCESS_TOKEN:+set}"
echo "${ZOOM_DOCS_MCP_ACCESS_TOKEN:+set}"

If empty, export the relevant token using concepts/oauth-setup.md.

2. Tool discovery working?

• Confirm the client can see recordings_list, search_meetings, get_meeting_assets,

and get_recording_resource.

• For the dedicated Zoom Docs server, confirm the client can see create_file_with_content

and get_file_content.

• If your client exposes raw protocol inspection, verify tools/list succeeds.
• Compare the visible tools with references/tools.md.

3. Correct OAuth scopes on the token?

Minimum Zoom MCP scopes for this guide:

• ai_companion:read:search — Search across Zoom Meeting, Zoom Chat, and Zoom Doc
• meeting:read:search — Search and view meetings
• meeting:read:assets — View a meeting's assets
• cloud_recording:read:list_user_recordings — Lists all cloud recordings for a user.
• cloud_recording:read:content — read recording content scope

Minimum Zoom Docs MCP scopes:

• docs:write:import — Create new file by import
• docs:read:export — Read file content in Markdown format

Whiteboard uses a separate scope set. See whiteboard/SKILL.md.

4. AI Companion features enabled?

Go to Zoom web portal → Admin → Account Management → Account Settings → AI Companion. Confirm Smart Recording and Meeting Summary are enabled if you expect semantic search, meeting assets, or transcript-rich recording content to be useful.

Quick Fixes

Auth Reality Check

Use user OAuth as the documented execution path for Zoom MCP content tools in this plugin. Do not rely on Server-to-Server OAuth as a supported MCP auth model here.

Where to Get Help

• Developer forum: https://devforum.zoom.us/
• Zoom support: https://support.zoom.com/
• MCP protocol docs: https://modelcontextprotocol.io/

Common Errors — Zoom MCP Server

Diagnostic guide for the most frequent issues when using the Zoom MCP server.

Authentication Issues

Access token is required (-32001)

Cause: The bundled connector does not have a token available, so no Authorization header is sent to the Zoom MCP endpoint.

Fix: Set ZOOM_MCP_ACCESS_TOKEN and restart Claude Code or re-enable the plugin.

export ZOOM_MCP_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

Invalid access token (-32001)

Cause: The access token expired, was revoked, or does not contain the exact MCP scopes needed for the tool you called.

Fix: Refresh the token, update ZOOM_MCP_ACCESS_TOKEN, restart Claude Code, and verify the MCP-specific granular scopes.

Scope Issues

search_meetings fails on scope

Server-required scope: meeting:read:search

get_meeting_assets fails on scope

Server-required scope: meeting:read:assets

recordings_list fails on scope

Server-required scope: cloud_recording:read:list_user_recordings

get_recording_resource fails on scope

Server-required scope: cloud_recording:read:content

create_file_with_content fails on scope

Required scope: docs:write:import

get_file_content fails on scope

Required scope: docs:read:export

Search and Retrieval Issues

Semantic search returns no useful results

Common causes:

• AI Companion features were not enabled for those meetings
• the query is too narrow
• the date window is too narrow
• the meeting is easier to locate through recordings_list

Fixes:

• enable Smart Recording and Meeting Summary
• widen from and to
• try shorter search terms
• fall back to recordings_list

Meeting assets retrieval fails even with a valid token

Most often this means one of these:

• missing meeting:read:assets
• guessed meetingId instead of the right UUID or numeric ID
• user does not have access to that meeting's assets

Recording-oriented retrieval fails

If get_recording_resource cannot find the target:

• use recordings_list first
• use the identifier returned by the live listing flow
• avoid assuming a scheduled meeting number is the same identifier used by the recording flow

Direct resource download returns 401

Returned resource URLs still require the bearer token.

Fix: Include Authorization: Bearer YOUR_TOKEN when fetching the URL directly.

Connection Issues

Can not found tool: ... in this MCP Server (-32602)

Cause: The requested tool does not exist on the active MCP server, or the request was sent to the wrong MCP surface.

Fix:

• Zoom MCP: https://mcp-us.zoom.us/mcp/zoom/streamable
• Zoom Docs MCP: https://mcp.zoom.us/mcp/docs/streamable
• Whiteboard MCP: https://mcp-us.zoom.us/mcp/whiteboard/streamable
• re-run tools/list
• use the current tool names exposed by that server
• if the request is Zoom Docs-specific, use the dedicated Docs MCP server
• if the request is Whiteboard-specific, route to ../whiteboard/SKILL.md

MCP server not appearing in the client

Fix:

• confirm the plugin is enabled
• confirm ZOOM_MCP_ACCESS_TOKEN is set
• restart Claude Code so the bundled MCP server restarts

Parameter and Call-Handling Issues

Call handle error (-32603)

Cause: The tool call was accepted at the protocol layer, but the server failed while handling the call. One observed case was calling recordings_list without the required arguments.

Fix:

• re-check required parameters against the live schema from tools/list
• retry with the missing arguments added

Upstream 400 invalid param

Cause: The MCP tool reached the downstream Zoom API, but one of the passed arguments was invalid. One observed case was calling create_file_with_content with a bogus parent_id.

Fix:

• remove the bad argument or replace it with a valid value
• retry the tool call

Authentication and Identifiers — Whiteboard MCP

Guidance for https://mcp-us.zoom.us/mcp/whiteboard/streamable and https://mcp-us.zoom.us/mcp/whiteboard/sse.

Authentication Behavior

User OAuth

User OAuth with Whiteboard scopes was the verified working path for:

• list_whiteboards
• get_a_whiteboard

The required user OAuth scope set includes:

• whiteboard:read:list_whiteboards
• whiteboard:read:whiteboard

Server-to-Server OAuth

S2S OAuth can reach the Whiteboard MCP gateway and complete protocol discovery through tools/list, but Whiteboard read-tool execution must be validated separately for your app.

One possible runtime error shape when S2S lacks the expected scopes is:

Invalid access token, does not contain scopes:[whiteboard:read:admin,whiteboard:read]

Protected-resource metadata for Whiteboard MCP advertised these supported scopes:

• whiteboard:write:whiteboard
• whiteboard:read:list_whiteboards
• whiteboard:read:whiteboard

Practical guidance:

• Use user OAuth first for Whiteboard MCP.
• Only rely on S2S after you have confirmed the app can mint and execute with the required Whiteboard scopes.

Whiteboard ID Mapping

The MCP-facing whiteboard_id matches the URL segment after /wb/db/.

Example:

https://us05whiteboard.zoom.us/wb/db/6iktP8hJT3e5qaCuwFuAGg/p/180968285929472

• Correct MCP whiteboard_id: 6iktP8hJT3e5qaCuwFuAGg
• The numeric /p/... segment is not the Whiteboard MCP identifier.

Response Shape

get_a_whiteboard returned a list-style payload containing the matched whiteboard rather than an obviously single-object payload. Parse the response shape you actually receive from the live server instead of assuming the tool name implies a unique-object response.

Tools — Whiteboard MCP

Current tools/list result from https://mcp-us.zoom.us/mcp/whiteboard/streamable.

Tool Catalog

Supported Scope Families Advertised by Whiteboard MCP

Protected-resource metadata for Whiteboard MCP advertised:

• whiteboard:write:whiteboard
• whiteboard:read:list_whiteboards
• whiteboard:read:whiteboard