YouTube Transcript MCP server

---

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.

---

Links

• 🌐 YouTubeTranscript.dev
• 🔌 Hosted MCP
• 📖 API Documentation
• 💰 Pricing

---

License

MIT License — see LICENSE for details.