YouTube Transcript MCP Server

MCP server for YouTubeTranscript.dev — extract transcripts, manage history, and power AI assistants with YouTube content.

Website • Hosted MCP • API Docs • Pricing • Quick Start • Tools

Why This MCP Server?

Connect Claude, Cursor, Windsurf, or any MCP client to YouTubeTranscript.dev — no custom code. Your AI assistant gets tools to extract transcripts, list history, and manage content at scale.

⚡ Fast caption extraction — Manual or auto captions, returns in seconds
📚 Transcript history — List, search, and paginate your transcripts
🎯 Full control — Get stats, delete transcripts, fetch by video ID
🔌 One config — Works with Claude, Cursor, Windsurf, VS Code, Cline
🔒 User-owned keys — API key per connection, no server-side secrets

→ Get your free API key

Quick Start

Remote MCP URL: https://mcp.youtubetranscript.dev

Claude, Cursor, and VS Code can add this as a remote MCP connector. ChatGPT users must enable Developer mode and create a custom app with this URL; availability depends on the workspace plan. OAuth-capable clients sign in once, so no API key is needed in the chat.

Client	One-click
Claude	Add custom connector
ChatGPT	Developer mode / custom MCP app setup or Custom GPT
Cursor	Install
VS Code	Install
Claude Code	`claude mcp add --transport http youtubetranscript https://mcp.youtubetranscript.dev`
Grok	`grok mcp add --transport http youtubetranscript https://mcp.youtubetranscript.dev`

Full walkthrough: youtubetranscript.dev/resources/mcp-server

API key clients (if the tool has no OAuth): send Authorization: Bearer YOUR_API_KEY. x-api-token still works. Get a key from the account page.

Run locally (optional): npm install && npm run build && npm run start:http — then connect to http://localhost:8080.

MCP Connection Settings

Claude Code

claude mcp add --transport http youtubetranscript https://mcp.youtubetranscript.dev

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "youtubetranscript": {
      "url": "https://mcp.youtubetranscript.dev",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "youtubetranscript": {
      "url": "https://mcp.youtubetranscript.dev",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "youtubetranscript": {
      "serverUrl": "https://mcp.youtubetranscript.dev",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

VS Code + Copilot

settings.json:

{
  "mcp": {
    "servers": {
      "youtubetranscript": {
        "url": "https://mcp.youtubetranscript.dev",
        "headers": { "Authorization": "Bearer YOUR_API_KEY" }
      }
    }
  }
}

Cline

Add to your Cline MCP config (format may vary by Cline version):

{
  "youtubetranscript": {
    "url": "https://mcp.youtubetranscript.dev",
    "headers": { "Authorization": "Bearer YOUR_API_KEY" }
  }
}

Replace YOUR_API_KEY with your API key from youtubetranscript.dev/dashboard/account.

Configuration

Server Environment (for deployment)

Variable	Description	Default
`YTSM_BASE_URL`	Base URL of the API	`https://www.youtubetranscript.dev`
`MCP_PUBLIC_URL`	Public MCP origin	`https://mcp.youtubetranscript.dev`
`YTSM_TIMEOUT_MS`	Request timeout in ms	`30000`
`PORT`	HTTP server port	`8080`
`DEBUG`	Enable debug logging	`false` (set `true` to enable)

Note: HTTP mode uses OAuth where the client supports it, including compatible Claude, Cursor, VS Code, and Grok clients. ChatGPT requires Developer mode and a custom MCP app. API-key clients can send Authorization: Bearer / x-api-token from the client. Do not put user keys in server env. For stdio mode, set YTSM_API_KEY. Always set YTSM_BASE_URL to https://www.youtubetranscript.dev — the apex host 301s and breaks POST/auth.

Tools Reference

Tool	Best for	Returns
`get_stats`	Credits, transcripts count, plan	credits, transcripts_total, plan, rate_limit
`transcribe_v2`	Create/fetch transcript (fast)	Transcript JSON
`list_transcripts`	List user transcripts	History list with pagination
`get_transcript`	Get full transcript by video_id	Transcript detail
`delete_transcript`	Delete transcript(s)	Delete result

get_stats

Credits left, transcripts created, plan, rate limit. No parameters.

transcribe_v2

Fast caption-based transcript (no ASR). Uses manual or auto captions only.

Parameter	Required	Description
`video`	Yes	YouTube URL or 11-character video ID
`language`	No	Language tag (e.g. `en`, `en-US`)
`source`	No	`auto` (default) or `manual`
`format`	No	`{ timestamp, paragraphs, words }` booleans

list_transcripts

List transcript history for the authenticated user.

Parameter	Required	Description
`search`	No	Search by video id, title, or transcript text
`limit`	No	How many to return (default 10)
`page`	No	Page number (default 1)
`status`	No	`all`, `queued`, `processing`, `succeeded`, `failed`
`language`	No	Language filter (e.g. `en`)
`include_segments`	No	Include transcript segments in response

get_transcript

Get full transcript by video_id.

Parameter	Required	Description
`video_id`	Yes	YouTube video ID
`id`	No	Transcript record id for specific version
`language`	No	Language filter
`source`	No	`auto`, `manual`, or `asr`
`include_timestamps`	No	Include timestamps in response

delete_transcript

Delete transcript records.

Parameter	Required	Description
`ids`	No*	Array of transcript record ids to delete
`video_id`	No*	Convenience: delete by video id (resolves id)

*Provide at least one of ids or video_id.

Deployment (Optional)

For production, deploy to a service that supports long-lived connections (e.g. Cloud Run, Railway, Fly.io). Avoid serverless (Vercel, Lambda) for MCP — timeouts and concurrency limits cause issues.

docker build -f Dockerfile.cloudrun -t gcr.io/YOUR_PROJECT/youtube-transcript-mcp .
docker push gcr.io/YOUR_PROJECT/youtube-transcript-mcp
gcloud run deploy youtube-transcript-mcp --image gcr.io/YOUR_PROJECT/youtube-transcript-mcp ...

Stdio (Alternative)

Run as a subprocess instead of HTTP. Required: set YTSM_API_KEY in env (API key is not passed per-request for stdio).

{
  "mcpServers": {
    "youtubetranscript": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": { "YTSM_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Run from the project directory after npm run build. For globally installed package, use the path to dist/index.js in the package.

Development

npm install
npm run build
npm test
npm run start:http   # Local HTTP server (port 8080)

Quick test all tools (requires YTSM_API_KEY in env):

npm install && npm run build
export YTSM_API_KEY=your_key   # bash/mac
$env:YTSM_API_KEY="your_key"   # PowerShell
npm run test:all

See QUICK_TEST.md for full testing instructions.

License

MIT License — see LICENSE for details.

youtube-transcript-mcp

Documentation