zoom-recordings-server/README.md

MCP server for downloading Zoom Cloud Recordings (MP4 files only)

# Zoom Recordings MCP Server

**Version:** 1.0.0
**License:** ISC

MCP server for interacting with Zoom Cloud Recordings, allowing users to list, download MP4 video files, and retrieve VTT transcripts.

## Features

*   **List Cloud Recordings:** Fetches a list of a user's Zoom cloud recordings, with optional date range filtering and pagination.
*   **Get Specific Meeting Recordings:** Retrieves recording details for a specific meeting, including available MP4 files and transcripts.
*   **Download Recordings:** Downloads specific recording files (e.g., MP4 videos) to a local path.
*   **Get Transcripts:** Retrieves VTT transcript files for a meeting.
*   **Zoom API Integration:** Uses Zoom User-Level OAuth 2.0 for API authentication.
*   **Token Management:** Securely stores and refreshes Zoom API tokens in a `.zoom-tokens.json` file within a configurable data directory.
*   **MCP Standard:** Implements the Model Context Protocol for integration with MCP-compatible clients.

## Prerequisites

*   Node.js (version specified in `package.json` or latest LTS recommended)
*   A Zoom account with Cloud Recording enabled.
*   A Zoom OAuth App (User-managed app type) with the following details:
    1.  Go to the Zoom App Marketplace ([https://marketplace.zoom.us/](https://marketplace.zoom.us/)) and create a new **User-managed app** (select the "General App" type if prompted).
    2.  Once your app is created, find and save its **Client ID** and **Client Secret**. You will use these for the `ZOOM_CLIENT_ID` and `ZOOM_CLIENT_SECRET` environment variables.
    3.  In your app's configuration on the Zoom Marketplace, you must add an **OAuth Redirect URL**. For the purpose of obtaining the initial authorization code, `http://localhost:3000/callback` is a suitable value (this server does not host this callback; it's only used for the initial manual code retrieval).
    4.  Add the following **Scopes** to your app to grant the necessary permissions:
        *   `cloud_recording:read:list_user_recordings` (Allows listing all cloud recordings for the user)
        *   `cloud_recording:read:recording` (Allows reading/downloading specific recording files and transcripts)
        *   `cloud_recording:read:list_recording_files` (Allows listing individual files within a recording)
        *   `user:read:user` (Allows viewing user information - useful for troubleshooting)
    5.  To generate the one-time `AUTHORIZATION_CODE` needed for your MCP Config file, you'll construct a URL and visit it in your browser. 
    * Example URL: https://marketplace.zoom.us/authorize?client_id=CLIENT_ID&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fcallback&scope=cloud_recording:read:list_user_recordings,cloud_recording:read:recording,cloud_recording:read:list_recording_files,user:read:user

## Setup

1.  **Clone the repository:**
    ```bash
    git clone <your-repository-url>
    cd zoom-recordings-server
    ```

2.  **Install dependencies:**
    ```bash
    npm install
    ```

3.  **Build the TypeScript code:**
    ```bash
    npm run build
    ```
    This compiles the TypeScript files from `src` to JavaScript in the `build` directory and makes the main script executable.

4.  **MCP Configuration Example**

    Below is an example of how to configure this server in your MCP client (e.g., `claude_desktop_config.json`).

    ```json
    {
    "mcpServers": {
        "zoom-transcripts": {
        "command": "/path/to/your/node",
        "args": ["/path/to/zoom_urbn_mcp/build/index.js"],
        "env": {
            "ZOOM_CLIENT_ID": "YOUR_ZOOM_CLIENT_ID",
            "ZOOM_CLIENT_SECRET": "YOUR_ZOOM_CLIENT_SECRET",
            "AUTHORIZATION_CODE": "YOUR_ONE_TIME_AUTHORIZATION_CODE",
            "ZOOM_DATA": "/path/to/your/zoom_data_directory"
        }
        }
    }
    }
    ```

    Replace `/path/to/your/node` with the absolute path to your Node.js executable (e.g., /usr/local/bin/node, or the path from 'which node'). Alternatively, if 'node' is in your system's PATH and you want to use the default version, you can simply use "node".  You can find the path to your Node.js executable by running:

    ```bash
    which node
    ```

## MCP Tools Provided

This server exposes the following tools via the Model Context Protocol:

*   **`list_recordings`**: Lists cloud recordings for the authenticated user.
    *   Parameters:
        *   `dateRange` (optional): Object with `from` and `to` properties (YYYY-MM-DD format) to filter recordings.
        *   `pageSize` (optional): Number of recordings per page (default: 30).
        *   `nextPageToken` (optional): Token for fetching the next page of results.
*   **`get_meeting_recording_details`**: Fetches details for a specific meeting's recordings.
    *   Parameters:
        *   `meetingId`: The ID or UUID of the Zoom meeting.
*   **`download_recording_file`**: Downloads a specific recording file.
    *   Parameters:
        *   `meetingId`: The ID or UUID of the Zoom meeting.
        *   `recordingFileId`: The ID of the specific recording file to download.
        *   `downloadPath` (optional): The local file path to save the downloaded file. If not provided, a default path within `ZOOM_DATA` might be used.
*   **`get_transcript`**: Retrieves the VTT transcript for a meeting.
    *   Parameters:
        *   `meetingId`: The ID or UUID of the Zoom meeting.
        *   `transcriptType` (optional): Specify the type of transcript if multiple are available (e.g., 'VTT').

## Key Implementation Notes

*   **Token Storage**: Zoom API tokens (`access_token`, `refresh_token`) are stored in a file named `.zoom-tokens.json` located in the directory specified by the `ZOOM_DATA` environment variable (or `./zoom_data` by default). This file should be kept secure and ideally added to `.gitignore` if `ZOOM_DATA` is within the project directory.
*   **Fetching Meeting Recordings**: Due to Zoom API limitations (the `/meetings/{meetingId}/recordings` endpoint might not be available for all user-level app types or configurations), this server first fetches a list of all user recordings (e.g., via `/users/me/recordings`) and then filters by the provided `meetingId` to find the specific meeting's recordings. This workaround ensures functionality across different Zoom account setups.

## Dependencies

*   `@modelcontextprotocol/sdk`: For MCP server implementation.
*   `axios`: For making HTTP requests to the Zoom API.
*   `dotenv`: For loading environment variables from a `.env` file.
*   `fs-extra`: For file system operations (like ensuring directory existence and managing token files).
*   `typescript`: For TypeScript support.

## Contributing

(Details on how to contribute to the project, if applicable)

## License

This project is licensed under the ISC License. See the `LICENSE` file for details.