# zoom-mcp

An intelligent [Model Context Protocol](https://modelcontextprotocol.io/) server for Zoom — giving AI agents rich, structured access to recorded meetings.

## What it does

Five tools that work together as a system:

| Tool | What it returns |
|------|----------------|
| `search_meetings` | Ranked list of recordings by fuzzy topic/name match |
| `get_meeting_brief` | Decisions + action items + key quotes (AI summary + transcript, combined) |
| `get_full_transcript` | Clean verbatim transcript with speaker labels |
| `extract_action_items` | Aggregated action items across a date range or single meeting |
| `search_meeting_content` | Full-text search across multiple meetings' transcripts |

Typical agent flow:
```
search_meetings("Q1 planning") → get_meeting_brief(meeting_id) → done
```
or:
```
extract_action_items(from_date="2026-03-01") → "here are all follow-ups from the last month"
search_meeting_content("rebrand timeline") → "mentioned in 3 meetings, here are the quotes"
```

## Setup

### 1. Create a Zoom OAuth App

1. Go to [marketplace.zoom.us/develop/create](https://marketplace.zoom.us/develop/create)
2. Choose **General App** (User-managed OAuth)
3. Add scopes: `recording:read`, `meeting:read`
4. Set redirect URI: `http://localhost:8090/callback` (for local) or your production URL
5. Copy **Client ID** and **Client Secret**

> **Why not Server-to-Server OAuth?** Zoom restricts cloud recording access to User-managed OAuth apps only. Server-to-Server apps cannot access the `recording:read` scope.

### 2. Configure environment

```bash
cp .env.example .env
# Edit .env with your ZOOM_CLIENT_ID and ZOOM_CLIENT_SECRET
```

### 3. Install

```bash
# Requires Python 3.11+ and uv
uv pip install -e .
```

### 4. Authenticate (one-time)

```bash
zoom-mcp-auth
```

This opens your browser, completes the OAuth flow, and saves an encrypted token to `.tokens/`. You only need to do this once (tokens auto-refresh).

### 5. Run the server

```bash
zoom-mcp
# Server starts on http://localhost:8080
```

Connect with MCP Inspector to verify tools:
```bash
npx @modelcontextprotocol/inspector http://localhost:8080/mcp
```

---

## Deployment on GCP Cloud Run

```bash
# Build and push
gcloud builds submit --tag gcr.io/YOUR_PROJECT/zoom-mcp

# Deploy
gcloud run deploy zoom-mcp \
  --image gcr.io/YOUR_PROJECT/zoom-mcp \
  --platform managed \
  --region us-central1 \
  --set-env-vars ZOOM_CLIENT_ID=...,ZOOM_CLIENT_SECRET=...,ZOOM_REDIRECT_URI=https://YOUR_SERVICE_URL/auth/callback \
  --set-secrets TOKEN_ENCRYPTION_KEY=zoom-mcp-key:latest \
  --allow-unauthenticated
```

Mount a persistent volume (Cloud Storage FUSE or Filestore) for `.tokens/` so the token survives container restarts, or store the token in Secret Manager and load it at startup.

---

## Add to Claude / Cursor / Lovable

**Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "zoom": {
      "url": "http://localhost:8080/mcp"
    }
  }
}
```

**Claude Code:**
```bash
claude mcp add zoom --url http://localhost:8080/mcp
```

---

## Notes on Zoom AI summaries

- Requires **Zoom AI Companion** to be enabled on your account (admin setting)
- Summaries are available from `GET /meetings/{id}/meeting_summary`
- When unavailable, `get_meeting_brief` and `extract_action_items` fall back to transcript-based extraction automatically

## Notes on transcripts

- Auto-transcription must be enabled in your Zoom account (Settings → Recording → Cloud recording)
- Transcripts take **up to 24 hours** to process after a meeting ends
- Only the meeting host can access recordings via the API (user-level OAuth)