youtube-transcript-mcp

<p align="center"> <img src="https://youtubetranscript.dev/logo.svg" alt="YouTubeTranscript.dev" width="80" /> </p>

<h1 align="center">YouTube Transcript MCP Server</h1>

<p align="center"> <strong>MCP server for YouTubeTranscript.dev — extract transcripts, manage history, and power AI assistants with YouTube content.</strong> </p>

<p align="center"> <a href="https://youtubetranscript.dev">Website</a> • <a href="https://mcp.youtubetranscript.dev">Hosted MCP</a> • <a href="https://youtubetranscript.dev/api-docs">API Docs</a> • <a href="https://youtubetranscript.dev/pricing">Pricing</a> • <a href="#quick-start">Quick Start</a> • <a href="#tools-reference">Tools</a> </p>

<p align="center"> <a href="https://youtubetranscript.dev"><img src="https://img.shields.io/badge/API-v2-brightgreen" alt="API Version" /></a> <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License" /></a> </p>

---

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

1. Get Your API Key

Sign up at youtubetranscript.dev and grab your API key from the Dashboard.

2. Connect Your Client

Connect to https://mcp.youtubetranscript.dev with header x-api-token: YOUR_API_KEY. No local setup required.

See QUICK_TEST.md for step-by-step setup and testing.

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 ytscribe https://mcp.youtubetranscript.dev --header "x-api-token: YOUR_API_KEY"

Claude Desktop

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

{
  "mcpServers": {
    "ytscribe": {
      "url": "https://mcp.youtubetranscript.dev",
      "headers": { "x-api-token": "YOUR_API_KEY" }
    }
  }
}

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "ytscribe": {
      "url": "https://mcp.youtubetranscript.dev",
      "headers": { "x-api-token": "YOUR_API_KEY" }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ytscribe": {
      "serverUrl": "https://mcp.youtubetranscript.dev",
      "headers": { "x-api-token": "YOUR_API_KEY" }
    }
  }
}

VS Code + Copilot

settings.json:

{
  "mcp": {
    "servers": {
      "ytscribe": {
        "url": "https://mcp.youtubetranscript.dev",
        "headers": { "x-api-token": "YOUR_API_KEY" }
      }
    }
  }
}

Cline

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

{
  "ytscribe": {
    "url": "https://mcp.youtubetranscript.dev",
    "headers": { "x-api-token": "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://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: The API key is not set in server env for HTTP mode. Users provide it via x-api-token or Authorization: Bearer when connecting. For stdio mode, set YTSM_API_KEY in env.

---

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": {
    "ytscribe": {
      "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.