# YouTube Transcript MCP Server

A self-hosted [Model Context Protocol](https://modelcontextprotocol.io/) 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

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

## 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`

```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:

```bash
npm run serve
```

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

```bash
tailscale funnel --bg 3000
```

Use the resulting URL with `/mcp`, for example:

```text
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:

```bash
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:

```text
[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

```bash
npm run build
npm test
npm run serve
```

## License

ISC