zoom-reports-mcp
README.md
# zoom-reports-mcp
Read-only Zoom reports for sales-meeting attendance and show rate. Check whether the host joined a meeting, for how many minutes, and how often they were in the room with at least one other person. This is a local prototype, not a production service.
It talks to Zoom in two ways, and both use the same code:
- an MCP server for Claude Code or Claude Desktop
- a CSV command for anyone who just wants a spreadsheet
```bash
zoom-reports-mcp attendance --input meetings.csv --output attendance.csv
```
## Read-only guarantee
The Zoom API client can send only two kinds of HTTP call:
| Call | Why |
| --- | --- |
| `POST https://zoom.us/oauth/token` | Server-to-Server OAuth. This mints a token. It does not change meetings, users, or recordings. |
| `GET https://api.zoom.us/v2/report/...` | Read a report. |
Every other method (`POST`, `PUT`, `PATCH`, `DELETE`) to the Zoom API is refused in code before a request is sent. Redirects are not followed. The access token is kept in memory, refreshed shortly before the one-hour expiry, and is never logged or returned. `ZOOM_ACCOUNT_ID`, `ZOOM_CLIENT_ID`, and `ZOOM_CLIENT_SECRET` are read from the environment only.
Tools whose scope is not on the token return a short explanation that names the scope. They do not raise a traceback.
## What you can ask
| Tool or command | What it answers |
| --- | --- |
| `get_meeting_participants` | Who joined one past meeting. Pages of 300, following `next_page_token`. |
| `check_attendance` | Did the host attend, for how many minutes, and (if you pass another person's email) were they in the meeting at the same time? |
| `list_user_meetings` | Past meetings for one host between two dates. |
| `show_rate_summary` | Per meeting, did the host attend with at least one other person, plus that show-rate count. |
| `attendance` CSV | The same attendance check for every row of a spreadsheet. |
Participant `duration` from Zoom is **seconds**, and a person who drops off and rejoins is several rows. Attendance minutes are those seconds added up, then converted to minutes. Time spent only in the waiting room does not count.
A few Zoom rules that change the answer:
- A numeric meeting id returns the **latest instance** of that id. Recurring meetings need the meeting UUID. UUIDs that start with `/` or contain `//` are double-encoded for you; pass the raw UUID.
- The user meeting report only includes meetings with **two or more** unique participants, only **one calendar month** at a time, and only the **past 6 months**. This server splits longer ranges into months and refuses anything older than that.
- The host and the other person must have joined with an email Zoom recorded. A guest who never signs in often has a blank email and will look like they were not there.
- Report APIs are rate-limit label **Heavy**. Calls are one at a time. A `429` waits for `Retry-After`, or backs off, and then retries. A month of meetings can take a while on purpose.
`list_user_meetings` and `show_rate_summary` need a scope the app may not have yet. Until it is added they return the missing-scope message and do not call the meetings endpoint.
## CSV
Input columns:
| Column | Required |
| --- | --- |
| `meeting_id` | yes |
| `host_email` | yes, the meeting host |
| `prospect_email` | no |
| `deal_id` | no |
Any other columns are copied through. The output always starts with `meeting_id`, `host_email`, `prospect_email`, `deal_id`, then your extra columns, then:
| Column | Meaning |
| --- | --- |
| `host_attended` | `true` or `false` |
| `host_minutes` | total minutes across rejoins, two decimal places |
| `prospect_attended` | blank when no prospect email was provided |
| `prospect_minutes` | blank when no prospect email was provided |
| `overlap` | `true` when the host and the other person were in the meeting at the same time. Blank when no second email was provided, or when Zoom did not send enough times to tell. |
| `error` | blank on success. When this is set, ignore the attendance columns for that row. An error is not a no-show. |
A missing scope is written on every remaining row and Zoom is not called again for that file. One bad meeting does not stop the rest.
```csv
meeting_id,host_email,prospect_email,deal_id
81234567890,alice@example.com,bob@example.org,D-100
```
## Zoom app setup
Use a Server-to-Server OAuth app on your Zoom account. Do this once, as an admin.
1. Create a dedicated Zoom user for this prototype, not a person's login. Something like `zoom-reports@example.com`.
2. Create a custom role that can **view reports only**. Do not grant meeting admin, user admin, or recording admin. Assign that role to the dedicated user.
3. In the Zoom Marketplace, create a **Server-to-Server OAuth** app. Name it so it is obvious, for example `Attendance reports (read-only)`.
4. Add scopes. Participant reports are enough for attendance checks. Add the user meeting-report scope when you want lists and the show-rate summary. Do not add the sign-in activity scope; this server does not call that API. Attendance uses the meeting participant report, not the past-meeting participants API.
| Marketplace name | Scope | Used by |
| --- | --- | --- |
| View meeting participant reports | `report:read:list_meeting_participants:admin` | participants, attendance, the summary's per-meeting check |
| View meeting reports for a user | `report:read:user:admin` | `list_user_meetings` and `show_rate_summary` |
5. Do not add any scope that can create or change Zoom data. Activate the app.
6. Copy the Account ID, Client ID, and Client Secret into your secrets manager. They are the three environment variables below.
The legacy scope `report:read:admin` also satisfies both report calls, if an older app already has it.
## Keep the secrets safe
Do not commit the client secret or paste it into a shell profile as plain text. Keep the three values in a secrets manager and inject them as environment variables when the server starts (most secrets managers have a CLI that can run a command with secrets injected).
## Install
Install [uv](https://docs.astral.sh/uv/) so `uvx` is on your `PATH`. Install this project from `git+https://github.com/Pathos-Global-Management/zoom-reports-mcp.git`.
### Claude Code
Copy-paste form. Replace the three dots with your values; never commit them anywhere:
```bash
claude mcp add zoom-reports \
--env ZOOM_ACCOUNT_ID=... \
--env ZOOM_CLIENT_ID=... \
--env ZOOM_CLIENT_SECRET=... \
-- uvx --from git+https://github.com/Pathos-Global-Management/zoom-reports-mcp.git zoom-reports-mcp
```
That command stores the environment on the MCP server entry in your local Claude config.
### Claude Desktop
Put this in `claude_desktop_config.json`:
```json
{
"mcpServers": {
"zoom-reports": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/Pathos-Global-Management/zoom-reports-mcp.git",
"zoom-reports-mcp"
],
"env": {
"ZOOM_ACCOUNT_ID": "...",
"ZOOM_CLIENT_ID": "...",
"ZOOM_CLIENT_SECRET": "..."
}
}
}
}
```
Restart Claude Desktop after saving. The server process speaks MCP on stdio. It does not open a port.
With no command, `zoom-reports-mcp` is the MCP server. It will look idle. That is the client waiting for Claude.
## Smoke test
With the three environment variables set, this fetches one token and one participant report, then prints a redacted summary. Names and emails are masked. The token is not printed.
```bash
uvx --from git+https://github.com/Pathos-Global-Management/zoom-reports-mcp.git zoom-reports-mcp --selftest 81234567890
```
From a checkout:
```bash
uv run zoom-reports-mcp --selftest 81234567890
```
A good run looks like this:
```text
zoom-reports-mcp self-test (read-only)
Token: acquired, refresh in about 3540s (token not shown)
Scopes: report:read:list_meeting_participants:admin
Meeting: 81234567890
Participant rows: 2
Sample: A*** a***@example.com joined 2026-11-01T15:00:00Z status in_meeting
Calls: POST https://zoom.us/oauth/token and GET /v2/report/meetings/{id}/participants
```
If the meetings scope is not on the app yet, participant checks still work. Listing meetings tells you to add `report:read:user:admin`. After you add a scope, run the command again. The next call asks Zoom for a new token.
## Develop
Python 3.11 or newer.
```bash
uv sync
uv run pytest
uv run zoom-reports-mcp
```
`uv run zoom-reports-mcp` starts the stdio server. `uv run pytest` runs the unit tests and the Gherkin acceptance specs in `tests/acceptance/features/`. HTTP is mocked. Nothing in the test suite calls Zoom.
There are no live credentials in this prototype. Do not point the tests at a real account. Use `--selftest` yourself when you want one real read.
## License
This project is licensed under the Apache License, Version 2.0. It is provided AS IS, with no warranty or liability. See [LICENSE](LICENSE).
## Trademarks
This project is not affiliated with, endorsed, or sponsored by Zoom Video Communications, Inc. Zoom is a trademark of Zoom Video Communications, Inc.
## Your data and responsibilities
The server runs locally and uses the Zoom credentials you supply. You are responsible for complying with Zoom's API and Marketplace terms, and with applicable privacy law such as GDPR, when processing participant data. There is no telemetry. Participant data is not sent anywhere except Zoom's API.
## Read-only
This program never creates, updates, or deletes anything in Zoom. The only requests it sends are an OAuth token request and GET calls to Zoom report endpoints.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues