zoom-mcp

MCP server for Zoom's Users Admin REST API. Wraps the official https://developers.zoom.us/docs/api/users/ spec — Users and Groups — driven by PRD-14714's "Account creation / validation" requirement (onboarding step: account creation and group-driven provisioning, plus validation). 15 tools, trimmed down from an original 71-tool full-API build (2026-08-04), then trimmed again from 22 to 15 (2026-08-07) — see Scope below.

Tool Scope

Trimmed from 22 tools to 15 tools (2026-08-07). The kept surface is focused on core user-lifecycle management (create / get / list / update / delete / status / permissions) plus group membership management — together the two building blocks needed for typical onboarding and offboarding automation. Contact-group and division management (6 tools across contact_groups.py and divisions.py) were dropped as lower-value niche capabilities for that use case, along with zoom_delete_a_group (group deletion is a rare, high-risk admin action outside the normal onboarding/offboarding flow). See the Scope section below for the full before/after mapping.

Naming note: Zoom also publishes its own first-party MCP servers (developers.zoom.us/docs/mcp) — Zoom, Whiteboard, Chat, Docs, Tasks, Canvas, Revenue Accelerator, Meetings. Investigated and confirmed those are scoped entirely to meeting/chat/document/whiteboard content access via per-user OAuth 2.1 (Claude/ChatGPT connector style) — none of them expose user/account administration. This server instead wraps Zoom's standard Admin REST API (https://api.zoom.us/v2) directly, which is the only place account creation/validation actually lives.

Related MCP server: Zoom API MCP Server

Overview

• Stateless HTTP service. No credentials are ever persisted — each request supplies its own Server-to-Server OAuth app credentials via headers, used only for the lifetime of that single request.

• Supports concurrent requests; per-request credential isolation is done via Python contextvars, not a global/shared client instance.

• Entry points: POST /mcp (MCP protocol) and GET /health (health check).

• Default port: 8080 (configurable via MCP_HTTP_PORT).

• All tools were generated mechanically from Zoom's own published OpenAPI 3.0 spec (https://developers.zoom.us/api-hub/users/methods/endpoints.json, the machine-readable source behind the public docs page) — path/query parameters and request-body fields are flattened into named function arguments; nested object/array-of-object fields (e.g. user_info, members, feature) are passed through as a raw dict/list[dict] matching the vendor's own schema shape.

Scope

15 tools, trimmed down from an original 71-tool full-API build (2026-08-04), by way of an intermediate 22-tool build. MSPbots has no existing "Zoom" integration configured (confirmed via web/int/sys/integration/list), so — matching the approach used for duo-mcp elsewhere in this program — "actual usage" was taken from the original PRD-14714 task's own stated requirement instead: account creation and group-driven provisioning, plus validation. That maps to:

• users (8 of 35 original): zoom_create_users, zoom_check_a_user_email (email-availability validation), zoom_get_a_user, zoom_list_users, zoom_update_a_user, zoom_delete_a_user, zoom_update_user_status (activate/deactivate — part of provisioning/validation), zoom_get_user_permissions

• groups (7 of 21 original): zoom_list_groups, zoom_create_a_group, zoom_get_a_group, zoom_update_a_group, plus membership management (the "group-driven" half of provisioning) — zoom_list_group_members, zoom_add_group_members, zoom_delete_a_group_member

Everything else (assistants, collaboration devices, meeting summary templates, password/profile-picture/presence/scheduler/settings/virtual- background management on users; admins/channels/locked-settings/webinar- registration/virtual-background/zoom_delete_a_group on groups; all of contact_groups and divisions — ~56 tools) was removed as unrelated to account creation/provisioning/validation, or (in the case of zoom_delete_a_group, contact groups, and divisions) as lower-value/niche for typical onboarding-offboarding automation use cases. If a removed operation is needed later, the vendor's OpenAPI spec (linked above) still documents it and it can be re-added the same way the kept tools were generated.

Authentication

Zoom's Users Admin API uses Server-to-Server OAuth (the account_credentials grant — a fully backend two-legged OAuth flow, no user redirect):

POST https://zoom.us/oauth/token?grant_type=account_credentials&account_id=<accountId>
Authorization: Basic base64(clientId:clientSecret)
-> {"access_token": "...", "expires_in": 3599, "token_type": "bearer"}

The access token is valid for only 1 hour and Zoom issues no refresh token, so this server performs a fresh token exchange on every single tool call rather than caching anything across MCP requests — the same "re-authenticate every call" approach used by several other vendor-mcp services in this fleet (webroot-mcp, tsheets-mcp, oitvoip-mcp, covedataprotection-mcp) whose upstream tokens are similarly short-lived or non-refreshable.

HEADER 授权参数说明

Missing any header returns 401:

{
  "error": "Missing credentials",
  "message": "This server requires the X-Zoom-Account-Id, X-Zoom-Client-Id, X-Zoom-Client-Secret headers",
  "required_headers": ["X-Zoom-Account-Id", "X-Zoom-Client-Id", "X-Zoom-Client-Secret"],
  "optional_headers": []
}

Invalid app credentials surface as a structured tool-level error envelope from the token exchange itself, e.g.:

{"error": {"code": "invalid_argument", "message": "Invalid client_id or client_secret", "retryable": false}}

Required scopes on the S2S OAuth app (set on the app's Scopes page in the Zoom App Marketplace) — grant the full set to use every tool below: user:read:admin, user:write:admin, group:read:admin, group:write:admin.

Environment Variables

MCP Endpoint

• POST /mcp — MCP protocol (streamable HTTP transport)

• GET /health — health check, returns {"status": "ok"} (pure local probe, does not call Zoom)

Tool List

Tool names are derived from each operation's own summary in Zoom's OpenAPI spec (e.g. "Check a user email" → zoom_check_a_user_email). The one naming collision — "Upload/Delete Virtual Background files" exists once for Groups and once for Users — is disambiguated with a group_/user_ prefix. dict/list[dict] parameters accept the vendor's own nested object shape as-is; see the API Reference link below for the exact sub-field names of each.

page_size maximums above are Zoom's own documented per-endpoint ceilings (from https://developers.zoom.us/api-hub/users/methods/endpoints.json), clamped server-side rather than left unbounded — they differ per endpoint (300 for /groups, 2000 for /users and /groups/{groupId}/members), so each tool clamps against its own real vendor maximum instead of a single shared constant.

Errors are returned as a structured JSON envelope (not raised as exceptions), e.g. {"error": {"code": "not_found", "message": "...", "retryable": false}}. code is one of: not_configured, unauthorized, not_found, invalid_argument, rate_limited, upstream_error.

测试示例

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-Zoom-Account-Id: <your-account-id>" \
  -H "X-Zoom-Client-Id: <your-client-id>" \
  -H "X-Zoom-Client-Secret: <your-client-secret>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "zoom_check_a_user_email",
      "arguments": {"email": "someone@example.com"}
    }
  }'

Structurally verified (2026-08-03): MCP handshake (initialize/ initialized), tools/list (71 tools, 0 schema errors, 0 name collisions), GET /health, and 401 credential-gating on /mcp all confirmed working against a locally running instance. A tool call made with a syntactically valid but fake Account ID/Client ID/Client Secret correctly reached Zoom's real OAuth endpoint and returned Zoom's own documented error shape (HTTP 400 {"reason":"Invalid client_id or client_secret","error":"invalid_client"}), confirming the request construction (Basic-auth-encoded client credentials, account_credentials grant, account_id param) is correct per Zoom's own documentation.

Re-verified after the 22→15 trim (2026-08-07): MCP handshake, tools/list (15 tools, 0 duplicate names), and GET /health confirmed working against a locally running instance.

API Reference

• Public, no login required: https://developers.zoom.us/docs/api/users/ (Users Admin API — human-readable docs for all 71 operations covered here)

• Public, no login required: https://developers.zoom.us/api-hub/users/methods/endpoints.json (the machine-readable OpenAPI 3.0 spec this server's tools were generated from — the authoritative source for exact nested-object field names inside any dict/list[dict] parameter)

• Public, no login required: https://developers.zoom.us/docs/internal-apps/s2s-oauth/ (Server-to-Server OAuth — how to create the app and generate access tokens)

Known Gaps

• Trimmed from 71 to 22 tools on 2026-08-04, then from 22 to 15 tools on 2026-08-07. The original build covered the full Users Admin API surface per an earlier scope decision (justified at the time by there being no MSPbots-existing integration to anchor a narrower scope against). A later scope decision cut this back to the original PRD-14714 task's actual stated capabilities (account creation, group-driven provisioning, validation) plus minimal supporting CRUD, landing at 22 tools. The 2026-08-07 pass narrowed this further to core user lifecycle (create/get/list/update/delete/status/permissions) and group membership management, dropping contact-group management, division management, and zoom_delete_a_group as lower-value/niche for typical onboarding-offboarding automation use cases — see the Scope section above for the exact mapping and the removed operations. If a removed operation is needed later, the vendor's OpenAPI spec (linked below) still documents it and it can be re-added the same way the kept tools were generated.

• No test S2S OAuth app credentials available yet — this build has not been end-to-end verified against a real Zoom account. Structural verification (handshake/tools-list/401 gating/real-OAuth-endpoint reachability) is complete; functional verification with real data is pending a test Account ID/Client ID/Client Secret with the required scopes.

• MSPbots has no existing "Zoom" integration configured (confirmed via web/int/sys/integration/list — no ZOOM/zoom entry exists), so there was no prior MSPbots interface/param shape to align this server's scope against; see Scope above for how the trim target was determined instead.

• Nested object/array-of-object body fields are passed through as a raw dict/list[dict] rather than flattened into individual named arguments (e.g. zoom_create_users' user_info, zoom_add_group_members' members) — this matches the flattening convention used across this fleet's other large, mechanically-generated vendor-mcps (connectsecure-mcp, covedataprotection-mcp, duo-mcp) for complex nested structures. Consult the OpenAPI spec link above for each dict's exact sub-field names.

• Some top-level fields Zoom's own spec does not literally mark required are nonetheless practically required for the call to succeed — e.g. zoom_create_users' user_info is optional per the spec's top-level required list (only action is marked required there), even though omitting it makes user creation meaningless. Required/optional markings here follow Zoom's spec literally rather than inferring intent, per this fleet's established practice of not second-guessing a vendor's documented contract.

• zoom_create_users' action="custCreate" requires a separate Zoom ISV sales agreement per Zoom's own docs — this server does not validate that prerequisite, Zoom's API will reject the call if it's not met.

Vendor MCP SOP (0818) Compliance Pass — 2026-08-19

Refactored to the stricter vendor-mcp-development-sop-0818.md:

• Errors are now a structured JSON envelope ({"error": {"code", "message", "retryable"}}) instead of ad-hoc f"Error: {e}" strings — code is one of the SOP's fixed vocabulary, mapped from the Zoom API's HTTP status.

• Responses are serialized with dump_json_capped() (compact, ensure_ascii=False, auto-truncates the largest list field past 20,000 chars) instead of json.dumps(..., indent=2).

• Tools are annotated with readOnlyHint / destructiveHint / idempotentHint (mcp.types.ToolAnnotations) per their actual read/write/reversibility semantics.

• Docstrings were rewritten to a short summary only; all per-parameter documentation (including the previously-embedded API: GET /xxx lines) moved into Annotated[T, Field(description=...)] on each parameter, and a service-level instructions string was added to FastMCP(...).

• page_size is now clamped server-side against Zoom's own documented per-endpoint maximum (300 for /groups, 2000 for /users and /groups/{groupId}/members — confirmed against Zoom's published OpenAPI spec, not assumed from the SOP's generic ≤200 fallback) rather than left unbounded.

• GET /health now returns exactly {"status": "ok"} (previously included extra service/transport fields not called for by the contract).

• api_client.py was rewritten around a shared module-level httpx.AsyncClient with SOP-compliant timeouts (connect=5.0, read=30.0, write=10.0, pool=5.0) and bounded retry/backoff on 429/5xx (respecting Retry-After, capped at 20s, max 3 retries) — previously each call opened its own short-lived client with a single flat 30s/60s timeout and no retry logic. In the process, ~50 methods for endpoints no tool ever called (divisions, contact groups, and various group/user sub-resources such as virtual-background upload, presence status, schedulers, and the profile-picture upload) were removed as dead code — they were left over from the original 71-tool generation pass and had no caller after the 71→22→15 trims described above.

• tools/resources.py, a same-purpose duplicate of the tool-registration wiring that only re-exported groups/users, was removed; server.py now registers both tool modules directly.

• Checked for the "tool registered under an always-false condition" dead-code pattern seen in an earlier repo (cisco-umbrella-mcp) — not present here; registration in server.py is unconditional.

• Confirmed no environment-variable credential fallback exists anywhere in this codebase (config.py holds no credential fields; the gateway middleware 401s outright if any of the three required headers is missing) — this was already compliant with SOP §3.1 before this pass, no change needed.

• Added tests/test_tools.py (tools/list snapshot incl. annotations and description-length assertions, plus error-code-mapping tests) and tests/test_middleware.py (401-on-missing/partial-header tests plus a contextvar-isolation test), per SOP §10's minimal test set. Added pytest/pytest-asyncio as dev dependencies.