Converts YouTube videos to audio files in multiple formats such as MP3, M4A, WAV, FLAC, AAC, OPUS, OGG, and WebM, with optional time clipping. Also fetches YouTube transcripts/captions in formats including text, JSON, LLM chunks, Markdown, SRT, and VTT.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@YouTube Audio & Transcript MCP Server Convert https://www.youtube.com/watch?v=jNQXAC9IVRw to a 320 kbps MP3 and give me the link."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP 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: 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.
Tool | What it does |
| Converts a YouTube URL to audio. Inputs: |
| Gets the transcript from existing captions. Inputs: |
| Checks a job that did not finish in time. Inputs: |
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): ....
Related MCP server: rippr
Open the YouTube Audio API on RapidAPI and subscribe to a plan.
To use youtube_transcript, also subscribe to the YouTube Transcript, Subtitle & Metadata API with the same account.
Copy your X-RapidAPI-Key from the endpoint playground. That value is your RAPIDAPI_KEY.
The server runs with npx, so you do not need to install anything else. It needs Node.js 18 or later.
RAPIDAPI_KEY=your-key npx -y github:pauliusdotpro/youtube-media-mcpAdd this to claude_desktop_config.json (Settings, Developer, Edit Config):
{
"mcpServers": {
"youtube-media": {
"command": "npx",
"args": ["-y", "github:pauliusdotpro/youtube-media-mcp"],
"env": {
"RAPIDAPI_KEY": "your-rapidapi-key"
}
}
}
}claude mcp add youtube-media --env RAPIDAPI_KEY=your-rapidapi-key -- npx -y github:pauliusdotpro/youtube-media-mcpAdd this to ~/.cursor/mcp.json, or to .cursor/mcp.json in your project:
{
"mcpServers": {
"youtube-media": {
"command": "npx",
"args": ["-y", "github:pauliusdotpro/youtube-media-mcp"],
"env": {
"RAPIDAPI_KEY": "your-rapidapi-key"
}
}
}
}Variable | Required | Default |
| Yes | None |
| No |
|
| No |
|
"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."
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.
npm install
npm run build
RAPIDAPI_KEY=your-key node dist/index.jsYou can test with the MCP Inspector: npx @modelcontextprotocol/inspector node dist/index.js.
MIT
Check the status of a job returned by youtube_to_audio or youtube_transcript when it did not finish in time. Long-polls up to waitSeconds (max 25). When the job is done: for api='audio' returns a fresh short-lived download link; for api='transcript' returns the transcript content. Failed jobs return the API error code and message.
| Name | Required | Description | Default |
|---|---|---|---|
| api | No | Which API created the job. Default: audio | |
| jobId | Yes | The jobId returned by youtube_to_audio or youtube_transcript | |
| maxChars | No | Transcript jobs only: truncate the returned transcript. Default: 100000 | |
| waitSeconds | No | Long-poll up to this many seconds for completion. Default: 25 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive semantics, but the description adds real behavioral detail beyond them: long-polling up to waitSeconds (max 25), api-dependent return shapes (a fresh short-lived download link vs. transcript content), and the failure path (API error code and message). That is substantially more than the structured fields convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the identifying purpose and condition, then the polling contract, then the return/error semantics. Every sentence carries distinct information with no repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description compensates by describing both success return values per api and the failure return values. Combined with 100% schema coverage, an agent has everything needed to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters including the waitSeconds maximum and the api enum. The description restates the waitSeconds cap and alludes to the api switch but adds no syntax or format detail beyond the schema — baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource ('Check the status of a job') plus the exact provenance of the resource ('returned by youtube_to_audio or youtube_transcript'), which cleanly separates it from both siblings. An agent can tell this is a polling/status tool, not a job-creation tool, without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear trigger condition: use it when a job 'did not finish in time' from one of the named sibling tools. It does not state any exclusions or failure fallbacks (e.g. what to do if the job is still pending after WaitSeconds), so it stops short of full when/when-not routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a public YouTube video or Shorts URL to an audio file and return a short-lived download link. Supports mp3 (default), m4a, wav, flac, aac, opus, ogg, webm; bitrate 128/192/256/320 kbps or standard/best; optional clip via startTime/endTime in seconds. Sources up to 3 hours. Returns link, fileName, fileSize and durationSeconds. Waits up to ~2 minutes; if the conversion is still running, returns a jobId to check later with get_job. The link expires (about 30 minutes), so download it promptly. Private, removed, age-restricted and live videos are not supported.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | YouTube video/Shorts URL (e.g. https://www.youtube.com/watch?v=jNQXAC9IVRw) or an 11-character video ID | |
| format | No | Output audio format. Default: mp3 | |
| endTime | No | Clip end in seconds (optional, must be greater than startTime) | |
| quality | No | Audio quality: kbps (128, 192, 256, 320), 'standard', or 'best'. Ignored for lossless wav/flac. Default: standard | |
| startTime | No | Clip start in seconds (optional) | |
| maxWaitSeconds | No | How long to wait for completion before returning a jobId. Default: 120 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, openWorldHint=true) by disclosing the ~2 minute wait ceiling, the jobId fallback path, the ~30 minute link expiry, and the unsupported source classes. These are exactly the operational traits an agent needs to sequence a download.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then formats, clipping, return values, timing behavior, and exclusions in a logical order. Slightly dense with one sentence repeating the schema's enum lists, but nearly every clause carries actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does so (link, fileName, fileSize, durationSeconds), plus timeout, expiry and source-limit behavior. Nothing an agent needs to invoke and then download the result is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with documented enums, so the schema already carries parameter meaning; the description largely restates the format/bitrate enumerations and the startTime/endTime clipping that are already in the schema. It adds little syntax or constraint detail beyond what is structured, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource+output (convert a public YouTube video/Shorts URL to an audio file) and immediately distinguishes itself from youtube_transcript and get_job by naming the download-link return. An agent can identify the tool's job without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear conditions for use and explicit exclusions: private, removed, age-restricted and live videos are not supported, and sources are capped at 3 hours. It also routes the agent to get_job when the wait times out. It does not, however, contrast this tool against the sibling youtube_transcript (audio vs. text), which is the main missing routing cue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the transcript of a public YouTube video or Shorts from its existing captions (manual or auto-generated). Formats: 'text' (plain transcript, default), 'json' (metadata plus timestamped segments), 'llm' (ordered timestamped chunks for RAG/summaries), 'markdown' (readable with timestamps), 'srt' or 'vtt' (subtitle files). Optionally pick a language tag (e.g. en, es, pt-BR) and caption source. When language is omitted the API prefers manual English, then automatic English, then the first available track. Waits up to ~2 minutes; if still running, returns a jobId for get_job. Fails with TRANSCRIPT_NOT_AVAILABLE when the video has no matching captions (no speech-to-text fallback).
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | YouTube video/Shorts URL or an 11-character video ID | |
| format | No | Output format. Default: text | |
| source | No | Caption source: preferred (default), manual (human captions only) or automatic (auto-generated only) | |
| language | No | Caption language tag such as en, en-US, de, pt-BR. Omit for automatic selection. | |
| maxChars | No | Truncate the returned transcript to this many characters. Default: 100000 | |
| chunkSize | No | Target characters per chunk for the 'llm' format (500-12000, default 4000) | |
| maxWaitSeconds | No | How long to wait for completion before returning a jobId. Default: 120 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond the safe-read annotations: the ~2 minute wait with jobId continuation, the TRANSCRIPT_NOT_AVAILABLE failure with no speech-to-text fallback, and the manual-English → auto-English → first-track selection order. These are exactly the operational traits an agent needs and are not in the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then formats, language rules, timeout and error handling in a logical progression with no filler. Dense but every sentence carries information; slightly long without visual breaks keeps it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter tool with no output schema, the description covers return shapes (formats and their contents), async completion via jobId, failure mode, and defaults. Combined with annotations that cover safety semantics, nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that 'llm' produces ordered timestamped chunks for RAG/summaries (the schema only names the enum), gives language tag examples, and clarifies chunkSize is only relevant to the 'llm' format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (get) plus resource (transcript), scoped to public YouTube videos/Shorts and existing captions (manual or auto-generated). Clearly distinct from youtube_to_audio (audio download) and tied to get_job via the async fallback, so an agent can route without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear operating context: default language-preference order, format selection for different downstream uses, and explicit routing to get_job when a jobId is returned. It also implies a when-not ('no speech-to-text fallback'), but does not explicitly say which sibling to use when captions are unavailable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_jobyoutube_to_audioyoutube_transcriptScored across 3 tools
Each tool targets a clearly distinct action: youtube_to_audio produces audio files, youtube_transcript retrieves captions, and get_job polls async jobs from either. There is no realistic overlap that would cause misselection.
The three names use three different patterns: youtube_to_audio (noun_to_noun with verb), youtube_transcript (noun_noun, no verb), and get_job (verb_noun). All are snake_case and readable, but the convention is mixed rather than predictable.
Three tools is lean but each earns its place: two capabilities plus the shared async-job poller. It is slightly minimal (no batch/playlist helper), but well-scoped for the server's narrow purpose.
The core surface (audio extraction, transcript retrieval, and job-status handling for both async flows) is fully covered with no dead ends. Minor gaps exist: no playlist/batch support and no lightweight video metadata lookup.
YouTube transcripts, search, channels, playlists and bulk transcript jobs for AI agents. 14 tools.
YouTube transcripts for AI agents: text, JSON, SRT, or VTT in 150+ languages, with AI fallback.
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents.
YouTube transcripts for any video, Short, channel or playlist: full text plus timestamped segments, caption language, and title, channel, views and duration. Built for RAG and summaries. Runs on Apify, $1.50 per 1,000 transcripts.
