# Riverside MCP Server

A local **stdio MCP server** for the Riverside Business API v3. It exposes every endpoint currently listed in Riverside's documentation as an MCP tool and includes a hand-authored OpenAPI 3.1 specification.

Works with Claude Desktop, Cursor, Codex, and other MCP clients that can launch a local stdio process.

## Requirements

- Node.js 20 or newer
- A Riverside Business API key (the API is available only to select Riverside Business accounts)

## Install

```bash
git clone YOUR_REPOSITORY_URL
cd riverside-mcp-server
npm install
npm run build
```

Do not place the API key in the repository. Supply it in your MCP client configuration.

## Client configuration

Use an absolute path to `dist/index.js`.

```json
{
  "mcpServers": {
    "riverside": {
      "command": "node",
      "args": ["/absolute/path/to/riverside-mcp-server/dist/index.js"],
      "env": {
        "RIVERSIDE_API_KEY": "YOUR_API_KEY",
        "RIVERSIDE_DOWNLOAD_DIR": "/absolute/path/to/downloads"
      }
    }
  }
}
```

This standard configuration shape is accepted directly by Claude Desktop and many other local clients. Cursor and Codex may store the same server definition in client-specific configuration files or expose an “Add MCP server” command.

## Available tools

| Tool | Purpose |
|---|---|
| `list_workspace` | List productions, studios, and projects |
| `list_recordings` / `get_recording` | Find and inspect recordings |
| `delete_recording` | Soft-delete a recording; requires `confirm: true` |
| `list_exports` / `get_export` | Find and inspect exports |
| `delete_export` | Permanently delete an export; requires `confirm: true` |
| `download_file` | Download a recording track file |
| `download_transcription` | Download SRT or TXT transcription |
| `download_export` | Download exported audio/video |
| `create_webinar_registrant` | Register a webinar participant |
| `get_webinar_registrants` | Search and paginate webinar registrants |
| `list_edits` | List edits/clips |
| `create_timeline_export` | Queue Premiere, Final Cut, or Pro Tools timeline export |
| `get_timeline_export` | Poll timeline export status |
| `download_timeline` | Download a completed timeline ZIP |

Downloads are written to `RIVERSIDE_DOWNLOAD_DIR`, or `./downloads` if it is omitted. Riverside download redirects are followed automatically. Errors are returned to the MCP client as structured tool errors without exposing the API key.

## OpenAPI

[`openapi.yaml`](./openapi.yaml) describes all 16 documented v3 operations. It is community-authored from Riverside's public documentation and is not an official Riverside artifact.

## Development and validation

```bash
npm test
npm run inspect
```

The server communicates only over stdout using MCP stdio. Diagnostics go to stderr so they do not corrupt protocol messages.

## Documentation source

- https://docs.riverside.fm/quickstart
- https://docs.riverside.fm/llms.txt

## License

MIT