# YouTube Audio & Transcript MCP Server

<!-- mcp-name: io.github.pauliusdotpro/youtube-media-mcp -->

An [MCP](https://modelcontextprotocol.io) server that lets AI agents (Claude Desktop, Claude Code, Cursor, and other MCP clients) convert YouTube videos to audio files and fetch YouTube transcripts.

It calls two RapidAPI APIs with **your own RapidAPI key**:

- [YouTube Audio Downloader & Converter](https://rapidapi.com/nbdy0/api/youtube-audio-downloader-converter): MP3, M4A, WAV, FLAC, AAC, OPUS, OGG and WebM, with clipping.
- YouTube Transcript, Subtitle & Metadata API (`youtube-transcript-subtitle-metadata-api.p.rapidapi.com`): existing manual or automatic captions as text, JSON segments, LLM chunks, Markdown, SRT or VTT.

## Tools

| Tool | What it does |
| --- | --- |
| `youtube_to_audio` | Converts a YouTube URL to audio. Inputs: `url`, `format` (default `mp3`), `quality` (`128`/`192`/`256`/`320`/`standard`/`best`), `startTime`, `endTime`, `maxWaitSeconds`. Returns a short-lived download `link`, `fileName`, `fileSize` and `durationSeconds`. Waits up to about 2 minutes, then returns a `jobId` if the conversion is still running. |
| `youtube_transcript` | Gets the transcript from existing captions. Inputs: `url`, `language` (for example `en`), `format` (`text` by default, or `json`, `llm`, `markdown`, `srt`, `vtt`), `source` (`preferred`/`manual`/`automatic`), `chunkSize`, `maxChars`, `maxWaitSeconds`. Returns the transcript content. |
| `get_job` | Checks a job that did not finish in time. Inputs: `jobId`, `api` (`audio` or `transcript`), `waitSeconds`. Returns a fresh link or the transcript when the job is done. |

Errors from the API are passed through with their code, for example `Error TRANSCRIPT_NOT_AVAILABLE (HTTP 422): ...` or `Error RAPIDAPI_NOT_SUBSCRIBED (HTTP 403): ...`.

## Get a RapidAPI key

1. Open the [YouTube Audio API on RapidAPI](https://rapidapi.com/nbdy0/api/youtube-audio-downloader-converter) and subscribe to a plan.
2. To use `youtube_transcript`, also subscribe to the YouTube Transcript, Subtitle & Metadata API with the same account.
3. Copy your `X-RapidAPI-Key` from the endpoint playground. That value is your `RAPIDAPI_KEY`.

## Install

The server runs with `npx`, so you do not need to install anything else. It needs Node.js 18 or later.

```bash
RAPIDAPI_KEY=your-key npx -y github:pauliusdotpro/youtube-media-mcp
```

### Claude Desktop

Add this to `claude_desktop_config.json` (Settings, Developer, Edit Config):

```json
{
  "mcpServers": {
    "youtube-media": {
      "command": "npx",
      "args": ["-y", "github:pauliusdotpro/youtube-media-mcp"],
      "env": {
        "RAPIDAPI_KEY": "your-rapidapi-key"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add youtube-media --env RAPIDAPI_KEY=your-rapidapi-key -- npx -y github:pauliusdotpro/youtube-media-mcp
```

### Cursor

Add this to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "youtube-media": {
      "command": "npx",
      "args": ["-y", "github:pauliusdotpro/youtube-media-mcp"],
      "env": {
        "RAPIDAPI_KEY": "your-rapidapi-key"
      }
    }
  }
}
```

## Environment variables

| Variable | Required | Default |
| --- | --- | --- |
| `RAPIDAPI_KEY` | Yes | None |
| `RAPIDAPI_AUDIO_HOST` | No | `youtube-audio-downloader-converter.p.rapidapi.com` |
| `RAPIDAPI_TRANSCRIPT_HOST` | No | `youtube-transcript-subtitle-metadata-api.p.rapidapi.com` |

## Example prompts

- "Convert https://www.youtube.com/watch?v=jNQXAC9IVRw to a 320 kbps MP3 and give me the link."
- "Get the audio from 1:00 to 2:30 of this video as FLAC."
- "Summarize this video from its English transcript."
- "Download Spanish subtitles for this video as SRT."

## Notes

- Download links are short-lived (results expire after about 30 minutes). Download the file soon after you get the link.
- Transcripts come from caption tracks that YouTube already has. If a video has no captions, the tool returns `TRANSCRIPT_NOT_AVAILABLE`. There is no speech-to-text fallback.
- Private, removed, age-restricted and live videos are not supported. Sources can be up to three hours long.
- Process only content that you own or have the right to use. This project is not affiliated with YouTube or Google.

## Development

```bash
npm install
npm run build
RAPIDAPI_KEY=your-key node dist/index.js
```

You can test with the MCP Inspector: `npx @modelcontextprotocol/inspector node dist/index.js`.

## License

MIT