YouTube Transcript MCP Server

An MCP server that provides tools for searching YouTube and fetching video transcripts. Uses the Supadata API for transcripts and the YouTube Data API for search, with optional Supabase caching.

Setup

npm install
npm run build

Environment Variables

| Variable | Required | Purpose | |---|---|---| | SUPADATA_API_KEY | Yes | Supadata REST API authentication | | YOUTUBE_API_KEY | No | YouTube Data API v3 key (enables search_youtube tool) | | SUPABASE_URL | No | Supabase project URL (enables caching) | | SUPABASE_SERVICE_ROLE_KEY | No | Supabase service role key (enables caching) |

• If YOUTUBE_API_KEY is not set, the search_youtube tool is disabled.
• If Supabase variables are not set, the server works without caching.

Supabase Setup (Optional)

Run the migration in supabase/migration.sql against your Supabase project to create the transcripts and transcript_jobs tables.

Usage

Claude Code

claude mcp add-json youtube-transcript '{
  "type": "stdio",
  "command": "node",
  "args": ["/path/to/youtube-transcript-mcp/dist/index.js"],
  "env": {
    "SUPADATA_API_KEY": "your-key",
    "YOUTUBE_API_KEY": "your-key"
  }
}' -s user

Claude Desktop

Add to your MCP config (claude_desktop_config.json):

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "node",
      "args": ["/path/to/youtube-transcript-mcp/dist/index.js"],
      "env": {
        "SUPADATA_API_KEY": "your-key",
        "YOUTUBE_API_KEY": "your-key"
      }
    }
  }
}

MCP Inspector

SUPADATA_API_KEY=your-key YOUTUBE_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js

Tools

search_youtube

Search YouTube for videos. Returns URLs, titles, channels, and descriptions.

• query (string, required): Search query
• max_results (number, optional, default 5): Number of results (1-25)

Requires YOUTUBE_API_KEY to be set.

get_transcript

Fetch a YouTube video's transcript.

• url_or_id (string, required): YouTube URL in any format or 11-char video ID
• format ("text" | "json", optional, default "text"): plain text or structured JSON with timestamps

Supported URL formats: youtube.com/watch?v=, youtu.be/, /shorts/, /embed/, /live/, /v/, m.youtube.com, music.youtube.com, youtube-nocookie.com, and bare video IDs.

get_transcript_job

Check status of an async transcript job (for long videos >20 minutes).

• job_id (string, required): Job ID from a prior get_transcript response