media-mcp
Enables AI agents to retrieve YouTube video transcripts, fetch metadata such as title, channel, duration, chapters, and caption languages, and download videos or audio for offline use.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
media-mcp
An MCP server that lets an AI agent read and download online video. It returns plain-text transcripts, video metadata with chapters and downloaded files, and uses yt-dlp as its only extraction engine. It runs over stdio by default and can serve Streamable HTTP behind a bearer token.
Transcripts are the fast path, because an agent reads text far more often than it needs a video file. Timestamps are off by default, long transcripts are saved to a file so they never flood the context, and one failing video never hides the others in a batch. An uncached transcript takes about 1.5 to 2.4 seconds and a cached one about a millisecond.
Requirements
Node 22.18 or newer and pnpm
yt-dlp 2026.10.26 or newer (
brew install yt-dlp), checked at startupffmpeg for downloads (
brew install ffmpeg), which only produces a warning when missing
Related MCP server: mcp-youtube-transcript
Install
pnpm install
pnpm build
claude mcp add media -- node "<abs path>/apps/server/dist/index.js"pnpm check runs lint, typecheck, build, tests and the dead code check. A live test against real YouTube runs with MEDIA_MCP_LIVE=1 pnpm vitest run packages/core/test/live.test.ts.
Tools
Tool | Purpose | Main inputs |
| Transcripts for one video, many videos or a playlist |
|
| Title, channel, duration, chapters and caption languages |
|
| Video as mp4 or audio as m4a, saved under the output folder |
|
| One page of a transcript saved to a file, for clients that cannot open files on the server |
|
Batch tools take 1 to 50 links plus
maxItemsandstartIndexto page through playlists. Anything cut off is reported undertruncations.Each entry is marked ok or failed, and a failure carries an error code, a message and a hint. A failure never stops the other entries.
Transcripts that fit the character budget come back inline. The rest are saved to
<output dir>/transcripts/with a preview, andread_transcript_filepages through them.Transcript text is wrapped in an
untrusted_contenttag, because it is third-party data and never instructions.
Configuration
Environment variables, read once at startup. Empty counts as unset, and a bad value stops the server with a readable message.
Variable | Default | Meaning |
|
| yt-dlp binary, use an absolute path when PATH is minimal |
|
| Root for downloads and saved transcripts |
| OS cache folder | Disk cache for transcripts and info |
|
| Parallel yt-dlp processes (1 to 16), downloads use their own pool of 2 |
|
| Transcript characters returned inline per call |
|
| Limit for one yt-dlp call that is not a download |
|
| Limit for one download |
|
| Largest file one download may produce |
|
| Cached info lifetime |
|
| Cached transcript lifetime, automatic captions 7 days |
|
|
|
| none | Required for |
|
| Bind address |
|
| Port |
| none | Extra |
Remote access
YouTube blocks most datacenter IPs, so free cloud hosts usually fail. Run the server on your own machine and expose it with a Cloudflare Tunnel.
openssl rand -hex 32
MEDIA_MCP_TRANSPORT=http MEDIA_MCP_HTTP_TOKEN=<token> \
MEDIA_MCP_HTTP_ALLOWED_HOSTS=<tunnel hostname> node apps/server/dist/index.js
cloudflared tunnel --url http://127.0.0.1:8787
claude mcp add --transport http media https://<hostname>/mcp --header "Authorization: Bearer <token>"POST /mcpcarries MCP,GET /healthzanswers 200 without a token, and every other route is refused.Requests need the bearer token and an allowed
Hostheader, which also blocks DNS rebinding.Connections, header time and body size are capped. The server warns when bound to a non-loopback address.
Anyone with the token can make the machine download into the output folder and read saved transcripts, so treat it like a password. There is one token, and restarting with a new one rotates it.
Architecture
packages/coreholds the domain types, theProviderport, the yt-dlp YouTube adapter, the disk cache, the process pools with a shared rate-limit gate, and the services. It has no MCP imports.apps/serveris the only package that imports the MCP SDK. It defines the tools and the stdio and HTTP transports.createMediaServicesinpackages/core/src/composition.tswires everything for both production and tests.Metadata requests try yt-dlp's fast
android_vrclient first and fall back once to the standard client. A rate limit pauses every yt-dlp process and retries once.
To extend it, add a provider as one folder in packages/core/src/providers/ plus a line in composition.ts, a tool as one file in apps/server/src/tools/ plus an export in tools/index.ts, and a transport as one file in apps/server/src/transports/ plus a line in select.ts.
Troubleshooting
The server fails fast on a missing yt-dlp or a bad setting, with the reason on stderr. Run
node apps/server/dist/index.jsby hand orclaude mcp listto see it.GUI clients often have a short PATH. Set
MEDIA_MCP_YTDLP_PATHto an absolute path.RATE_LIMITEDmeans YouTube is throttling this machine. Wait a few minutes, lowerMEDIA_MCP_CONCURRENCY, and update yt-dlp.
License
MIT, see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents.
Transcripts from YouTube videos, whole channels and playlists for AI agents, with bulk ZIP export.
YouTube transcripts for AI agents: 150+ languages, AI transcription fallback, search, summaries.
YouTube for AI agents: transcripts, comments, video stats, channel monitor, Shorts captions.
Related MCP Servers
- AlicenseAqualityBmaintenanceYouTube transcripts as token-efficient AI context. One fetch, cached. No yt-dlp, no API keys, no system dependencies. ~50 KB per video, instant re-reads from local cache.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP-compatible assistants to retrieve caption text from YouTube videos as either plain text or timestamped snippets for reading, summarizing, or searching. Supports local stdio and stateless HTTP deployments for integration with Claude Desktop, Claude Code, Cursor, and similar clients.MIT
- AlicenseBqualityCmaintenanceEnables AI agents to fetch the transcript, description, and comments of any YouTube video so they can read, summarize, and analyze video content. It ships a four-layer anti-blocking fallback cascade and disk caching for reliable, low-cost retrieval without API keys.4MIT
- AlicenseAqualityBmaintenanceExposes public YouTube data — transcripts with timestamps and language listings, keyword search, video metadata and statistics, comments, channels, channel uploads, and categories — as read-only tools an LLM can call over stdio. It runs as a single local process using only a YouTube Data API key, with SQLite caching, quota tracking, and no OAuth or account access.15MIT