YouTube Transcript MCP Server

A self-hosted Model Context Protocol server that lets MCP clients fetch publicly available YouTube caption tracks with timestamps. It does not transcribe audio. It supports Claude Desktop and other local stdio clients, plus ChatGPT and Claude web/API through a public HTTPS MCP endpoint.

How the integrations work

There are two connection modes:

Local Claude Desktop, Cursor, VS Code, and similar clients: the client starts dist/index.js over MCP stdio. YouTube requests are made from your computer.
ChatGPT custom MCP servers and Claude remote custom connectors: these clients need an MCP server reachable at a public https:// URL. Run this server locally and expose port 3000 with a tunnel. The server still fetches YouTube from your computer, so YouTube sees your residential IP rather than a cloud deployment IP.

The HTTP endpoint uses the official MCP SDK's Streamable HTTP transport. It also keeps a direct REST endpoint for scripts and health checks.

Security Notice: Official Hosting

This project is self-hosted. The author does not provide an official publicly hosted MCP server.

For security and privacy, clone this repository and run the server yourself, or deploy your own instance on infrastructure you control.

Be cautious of third-party websites claiming to host this project. They are not necessarily affiliated with the original project and may run modified code or collect information sent to their servers.

Official source code: https://github.com/windows10fan648/youtube-transcript-mcp

The author is not responsible for the security, privacy, or behavior of unofficial third-party deployments.

Quick start

git clone https://github.com/windows10fan648/youtube-transcript-mcp.git
cd youtube-transcript-mcp
npm install
npm run build
npm test

Publish to the MCP Registry

This repository includes a server.json manifest for the official MCP Registry. It describes the local stdio package; this project does not provide an officially hosted remote endpoint.

Before the first registry publication:

Confirm that the scoped npm package @fakasys/youtube-transcript-mcp is available and that you can publish it. The package name in package.json and packages[0].identifier in server.json must match.

Authenticate with npm, then build and inspect the package:

npm install
npm run build
npm pack --dry-run
npm publish --access public

Install the official mcp-publisher CLI from the MCP Registry releases.

Validate the manifest, authenticate with GitHub, and publish:

mcp-publisher validate
mcp-publisher login github
mcp-publisher publish

The mcpName value in package.json must match the name in server.json. Keep the package version in package.json and server.json synchronized for every release. Publish the npm package before publishing its registry metadata.

Claude Desktop over stdio

Add the following to Claude Desktop's configuration file:

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

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "node",
      "args": ["C:/path/to/youtube-transcript-mcp/dist/index.js"]
    }
  }
}

Use an absolute path, restart Claude Desktop, then ask Claude to transcribe a YouTube URL. This mode is local-only and does not make the server available to Claude web.

ChatGPT and Claude web/API over HTTPS

Start the MCP HTTP server:

npm run serve

In a second terminal, create a public HTTPS tunnel. Specifically use Tailscale Funnel

tailscale funnel --bg 3000

Use the resulting URL with /mcp, for example:

https://<YOUR_DOMAIN.ts.net/mcp

Security warning: Set MCP_AUTH_TOKEN before exposing the HTTP endpoint. When set, every HTTP endpoint except CORS preflight requires Authorization: Bearer <token>. Anyone who obtains an unprotected tunnel URL may be able to access its tools and consume your server's resources.

The server reads an optional YouTube session cookie only from the server-side YOUTUBE_COOKIE environment variable (with legacy COOKIE/YT_COOKIE environment fallbacks). Callers cannot provide or override cookies through query parameters, request bodies, or headers. Never commit or expose these cookies.

ChatGPT

In ChatGPT, open the custom connector/MCP server area, add the HTTPS /mcp URL, and enable the read-only tools. Depending on the ChatGPT surface or workspace, the UI may label this as adding a custom MCP server or creating a plugin. Then ask: List the available transcript languages for https://www.youtube.com/watch?v=... and summarize it in Spanish. ChatGPT can call the language-listing tool first, select the exact code, and then fetch that transcript.

The server does not run an LLM and does not need an API key. The summary tool fetches the transcript and returns it to ChatGPT with a summarization instruction; ChatGPT itself reads the tool result and writes the summary using the model already powering your conversation.

For the OpenAI API, configure a remote MCP tool with the same URL. The server supports Streamable HTTP and returns the transcript as MCP text content.

Claude web, Claude Desktop remote connectors, and Claude API

In Claude, open Customize → Connectors → Add custom connector and enter the public /mcp URL. Choose No sign in when MCP_AUTH_TOKEN is not set; if authentication is enabled, configure the connector to send the bearer token. Claude's remote connector connects from Anthropic's infrastructure, so the tunnel must remain running and publicly reachable.

For the Claude API, use the MCP connector with the public HTTPS URL and enable the list_youtube_transcript_languages, get_youtube_transcript, and summarize_youtube_transcript tools. Local stdio servers cannot be connected directly through the Claude API or Claude web's remote connector.

Direct REST API

The same server exposes optional REST requests:

MCP_AUTH_TOKEN='replace-with-a-long-random-token' npm run serve

curl -H 'Authorization: Bearer replace-with-a-long-random-token' \
  'http://localhost:3000/mcp?videoIdOrUrl=dQw4w9WgXcQ'

curl -X POST http://localhost:3000/mcp \
  -H 'Authorization: Bearer replace-with-a-long-random-token' \
  -H 'Content-Type: application/json' \
  -d '{"videoIdOrUrl":"dQw4w9WgXcQ","format":"text"}'

Tool reference

`get_youtube_transcript`

videoIdOrUrl — required YouTube URL or 11-character video ID. Supports watch URLs, youtu.be, shorts, embeds, live URLs, and mobile URLs.
lang — optional ISO 639-1/BCP-47 language code, including regional and script codes such as en, pt-BR, es-419, or zh-Hans. The server selects the exact exposed caption track and returns an error if it is unavailable; it never silently substitutes another language.

The tool returns timestamped plain text, for example:

[1s] [♪♪♪]
[18s] We're no strangers to love
[22s] You know the rules and so do I

`summarize_youtube_transcript`

videoIdOrUrl — required YouTube URL or 11-character video ID.
lang — optional transcript language code, including regional or script codes such as pt-BR or zh-Hans. This is still caption retrieval; the connected AI performs the summary.
style — optional brief, detailed, or bullets instruction for the connected AI client.

This is a client-assisted tool. It retrieves captions but does not transcribe audio or call OpenAI, llama.cpp, Ollama, or any other model itself.

`list_youtube_transcript_languages`

videoIdOrUrl — required YouTube URL or 11-character video ID.

Returns the caption tracks YouTube exposes, for example { "code": "zh-Hans", "name": "Chinese (Simplified)", "kind": "standard", "isAutoGenerated": false }. Pass the returned exact code as lang to get_youtube_transcript or summarize_youtube_transcript. If the requested language code is unavailable, the server returns an error listing the available language codes. Use this tool to check available languages before requesting a specific caption track.

YouTube access and limitations

This project reads publicly available caption tracks, including automatic captions when YouTube exposes them. It does not transcribe audio or bypass private videos, disabled captions, age restrictions, or YouTube authentication. YouTube's official Data API requires authorization for caption-track operations; this server uses YouTube's player caption data and an unofficial Node transcript library instead.

If YouTube challenges a cloud-hosted deployment, prefer local stdio or a local tunnel. If you must run in a cloud environment, set YOUTUBE_COOKIE in the server environment only; cookies in URLs, request bodies, or caller-controlled headers are intentionally ignored.

HTTP requests have a 1 MB JSON body limit and server-side request/header timeouts. PORT must be an integer from 1 through 65535.

Testing

npm run build
npm test
npm run serve

License

ISC

youtube-transcript-mcp

Documentation