youtube-captions-mcp

An MCP server that lets Claude read YouTube video transcripts, metadata, and search inside captions. Works with Claude Code, Claude Desktop, Claude.ai custom connectors, Cursor, and any other MCP-aware client.

No YouTube Data API key required. Metadata comes from the public oEmbed endpoint; captions come from YouTube's internal player API.

Tools

| Tool | Description | Arguments | | --- | --- | --- | | get_transcript | Full transcript as plain text with [H:MM:SS] timestamps | url (YouTube URL or 11-char ID), language? (BCP-47 code) | | get_video_info | Title, channel, description, duration, thumbnail, available caption languages | url | | search_transcript | Substring search across transcript segments, returns matches with timestamps | url, query, language?, limit? |

All tools accept either a full URL (https://www.youtube.com/watch?v=..., https://youtu.be/..., /shorts/..., /embed/..., /live/...) or a bare 11-character video ID. Errors for private videos, missing captions, and invalid URLs are surfaced with stable [CODE] prefixes so callers can branch on them.

Quick start — Claude Code

One command:

claude mcp add youtube-captions -- npx -y youtube-captions-mcp

Restart Claude Code and you can now ask things like:

Summarise https://www.youtube.com/watch?v=qp0HIF3SfI4 in 5 bullet points.

Find the part where Simon Sinek talks about "Martin Luther King" in that video and quote it.

Quick start — Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json) and add:

{
  "mcpServers": {
    "youtube-captions": {
      "command": "npx",
      "args": ["-y", "youtube-captions-mcp"]
    }
  }
}

Restart Claude Desktop. The three tools will appear in the tools drawer.

Manual install (from source)

git clone <this repo>
cd server
npm install
npm run build

Then point your MCP client at the absolute path of dist/index.js:

{
  "mcpServers": {
    "youtube-captions": {
      "command": "node",
      "args": ["/absolute/path/to/server/dist/index.js"]
    }
  }
}

Connect to Claude.ai (custom connector, SSE)

Claude.ai's remote MCP connectors speak HTTP + SSE. Run the SSE entry:

npm run start:sse             # listens on http://localhost:3333/sse
PORT=8080 npm run start:sse   # override the port

Expose it on a public URL (e.g. with ngrok http 3333 or a reverse proxy), then add it as a custom connector in Claude.ai:

• Name: yt-transcript
• URL: https://<your-public-host>/sse

The server keeps one MCP session per SSE connection; POST /messages?sessionId=... is used internally by the SDK for client→server messages. A GET /healthz endpoint reports status and active session count for basic monitoring.

Security note: the SSE entry has no authentication. Only expose it on trusted networks, or front it with a proxy that enforces auth if you are putting it on the public internet.

Development

npm run dev      # tsc --watch
npm run start    # runs dist/index.js (stdio)
npm run clean    # rm -rf dist

Error codes

All tool errors are prefixed with a stable code in square brackets:

• INVALID_URL — not a recognisable YouTube URL or ID
• VIDEO_UNAVAILABLE — removed, age-gated, region-blocked, etc.
• VIDEO_PRIVATE — video exists but is marked private
• NO_CAPTIONS — the video has no captions at all
• LANGUAGE_UNAVAILABLE — the requested language track does not exist
• METADATA_FETCH_FAILED — both oEmbed and the watch page failed to load
• TRANSCRIPT_FETCH_FAILED — underlying transcript fetch threw an unknown error