Zoom Phone + Virtual Agent MCP Server

A custom MCP server exposing Zoom Phone call data and Zoom Virtual Agent knowledge-base/engagement data as tools for an AI client (Claude Code, Claude Desktop, etc). Authenticates with Server-to-Server (Account) OAuth — no end-user login flow, no browser redirect. The server acts as your Zoom account directly.

1. Create the Marketplace app (one-time)

1. Go to https://marketplace.zoom.us/ → Develop → Build App.

2. Choose Server-to-Server OAuth.

3. Note the Account ID, Client ID, and Client Secret shown after creation.

4. Under Scopes, add (granular scopes):

   • phone:read:call_history:admin
   • phone:read:call_log:admin
   • phone:read:call_history
   • phone:read:call_log
   • phone:read:list_call_handling_settings:admin
   • phone:update:call_handling_settings:admin
   • km:read:list_articles:admin (or the current KM read scope shown in the app's scope picker)
   • km:write:article:admin
   • km:write:sync:admin
   • virtual_agent:read:list_engagements:admin
   • virtual_agent:read:list_transcripts:admin

   Scope names occasionally get renamed by Zoom — use the scope picker in your app as the source of truth; add only what the tools you actually plan to call require.

5. Activate the app.

2. Configure credentials

cp .env.example .env
# fill in ZOOM_ACCOUNT_ID, ZOOM_CLIENT_ID, ZOOM_CLIENT_SECRET

The server reads these from process.env — either export them in your shell, use a .env loader of your choice, or (recommended) pass them via your MCP client's config as shown below, so the secret never lives in a file you might commit.

3. Build

npm install
npm run build

4. Register with an MCP client

Claude Code:

claude mcp add zoom-phone-va \
  --command node \
  --args dist/index.js \
  --env ZOOM_ACCOUNT_ID=xxx \
  --env ZOOM_CLIENT_ID=xxx \
  --env ZOOM_CLIENT_SECRET=xxx

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "zoom-phone-va": {
      "command": "node",
      "args": ["/absolute/path/to/zoom-mcp-server/dist/index.js"],
      "env": {
        "ZOOM_ACCOUNT_ID": "xxx",
        "ZOOM_CLIENT_ID": "xxx",
        "ZOOM_CLIENT_SECRET": "xxx"
      }
    }
  }
}

Tools exposed

Zoom Phone

Tool	Purpose
phone_get_account_call_history	Account-wide call history, by date range
phone_get_account_call_logs	Account-wide call logs, by date range
phone_get_call_log_details	Single call log detail
phone_get_call_element	Single call leg/segment detail
phone_get_user_call_history	One user's call history
phone_get_user_call_logs	One user's call logs
phone_get_user_call_handling_settings	Read business/closed/holiday hour routing for a user
phone_update_user_call_handling_setting	Write — update a user's call routing config
phone_get_auto_receptionist_call_handling_settings	Read routing for an auto receptionist (IVR)
phone_update_auto_receptionist_call_handling_setting	Write — update auto receptionist routing config

Zoom Virtual Agent

Tool	Purpose
va_get_articles	List KB articles
va_get_article	Get one KB article
va_create_article	Write — create a KB article
va_update_article	Write — update a KB article
va_sync_knowledge_base	Write — trigger an external KB sync job
va_get_sync_status	Poll a sync job's status
va_get_engagements	Bot conversation session report
va_get_query_details	Query-level detail (what was asked, answered or not)
va_get_transcripts	Full conversation transcripts

Notes on the auth model

• S2S access tokens expire after 1 hour; src/zoomAuth.ts caches the token in memory and transparently refreshes ~60s before expiry. There is no refresh token in this flow — a new token is simply requested.
• All API calls run with the account's permissions — every tool call can see data across the whole account (subject to granted scopes), not just one user's. Scope your Marketplace app's granted scopes to only what you intend these tools to do.
• This flow is appropriate for backend automation on your own account. If you later need this server to act on behalf of other Zoom accounts/users, that requires switching to User OAuth (authorization code + refresh tokens) instead — a materially different auth model, not a drop-in swap.

Project layout

src/
  index.ts          # MCP server entry (stdio transport), registers all tools
  zoomAuth.ts        # S2S token fetch + in-memory cache/refresh
  zoomClient.ts      # Thin authenticated fetch wrapper for api.zoom.us/v2
  tools/
    phone.ts         # Zoom Phone tools
    virtualAgent.ts  # Zoom Virtual Agent tools