YouTube MCP

YouTube MCP

YouTube MCP lets an MCP client read YouTube video metadata, caption transcripts, comments, and search results. By default it needs no YouTube API key or account; an optional official YouTube Data API provider serves metadata, comments, and search with an API key.

Supports both stdio (local) and Streamable HTTP (VPS/remote) transports.

Access model

This is an independent, unofficial open-source project. It is not affiliated with, endorsed by, or sponsored by YouTube or Google.

• The default innertube provider serves metadata, comments, and search through youtubei.js, using an unofficial/internal YouTube interface without a YouTube Data API key. Unofficial access may change, break, be restricted, or be blocked.
• Select YT_PROVIDER=api and supply your own YOUTUBE_API_KEY to use the official YouTube Data API v3 for those three tools.
• Transcript tools always use youtube-transcript-plus, regardless of YT_PROVIDER. Transcript retrieval remains unofficial and does not use the official Data API path or your API key.

Users are responsible for deciding whether an access method suits their use and for complying with applicable service terms and law. See access methods and service terms for the tool/backend mapping, BYOK setup, limitations, and software licenses.

Features

Requirements

• Node.js 22 or newer. CI checks Node 22.21.0 and Node 24.

No YouTube API key required by default. The default innertube provider uses youtubei.js (an unofficial/internal YouTube interface) for video info, comments, and search. Transcripts always use youtube-transcript-plus. Neither needs an API key or authentication. See Providers for the optional official API.

Quick start

Your MCP client can run the published package without a clone:

npx -y @granitebps/youtube-mcp

The server uses stdio. Keep stdout reserved for MCP traffic.

Run from a cloned repository

To develop the server or use a clone directly:

git clone https://github.com/granitebps/youtube-mcp.git

cd youtube-mcp npm ci npm run build

Point your MCP client at the compiled entry point:

node /absolute/path/to/youtube-mcp/dist/index.js

Run npm run build after each source change. Do not use src or npm run dev as the client's stdio command; build output on stdout can corrupt MCP messages.

Client configuration

Each example starts with the npm package, followed by the local equivalent. Replace /absolute/path/to/youtube-mcp with your clone's path. Settings from Configuration can be added as environment variables.

Claude

Add the npm package to Claude Code:

claude mcp add youtube -- npx -y @granitebps/youtube-mcp

For a local build:

claude mcp add youtube -- node /absolute/path/to/youtube-mcp/dist/index.js

Claude Code uses local scope by default. Add --scope user before youtube to make the server available across projects.

Claude Desktop reads the same server from claude_desktop_config.json (on macOS, ~/Library/Application Support/Claude/claude_desktop_config.json). Restart the app after editing the file.

{

"mcpServers": { "youtube": { "command": "npx", "args": ["-y", "@granitebps/youtube-mcp"] } } }

For a local build, replace command and args with:

{

"command": "node", "args": ["/absolute/path/to/youtube-mcp/dist/index.js"] }

Codex

Add the npm package to ~/.codex/config.toml, or to .codex/config.toml in a trusted project:

[mcp_servers.youtube]

command = "npx" args = ["-y", "@granitebps/youtube-mcp"]

For a local build:

[mcp_servers.youtube]

command = "node" args = ["/absolute/path/to/youtube-mcp/dist/index.js"]

Restart Codex after editing the file.

OpenCode

Add the npm package to opencode.json or opencode.jsonc:

{

"$schema": "https://opencode.ai/config.json", "mcp": { "youtube": { "type": "local", "command": ["npx", "-y", "@granitebps/youtube-mcp"], "enabled": true } } }

For a local build, replace the command array with:

{

"command": ["node", "/absolute/path/to/youtube-mcp/dist/index.js"] }

Cursor

Add the npm package to .cursor/mcp.json in a project, or to ~/.cursor/mcp.json for global use:

{

"mcpServers": { "youtube": { "command": "npx", "args": ["-y", "@granitebps/youtube-mcp"] } } }

For a local build, replace command and args with:

{

"command": "node", "args": ["/absolute/path/to/youtube-mcp/dist/index.js"] }

GitHub Copilot (VS Code)

Add to your VS Code settings.json:

{

"mcp": { "servers": { "youtube": { "command": "npx", "args": ["-y", "@granitebps/youtube-mcp"] } } } }

VPS deployment (Streamable HTTP)

For remote deployment, the server runs as a persistent HTTP service using the Streamable HTTP transport (the current MCP standard, replacing the deprecated SSE transport).

1. Deploy to your VPS

# On your VPS

git clone https://github.com/granitebps/youtube-mcp.git cd youtube-mcp npm ci npm run build

Create .env (optional, for HTTP mode)

cp .env.example .env

Uncomment TRANSPORT=http, PORT, HOST as needed

YouTube often blocks datacenter IPs. If get_video_info returns ACCESS_BLOCKED with "Sign in to confirm you're not a bot", set YT_PROVIDER=api and YOUTUBE_API_KEY to serve metadata, comments, and search through the official API. See Providers.

2. Run with HTTP transport

# Using --http flag

node dist/index.js --http

Or using environment variable

TRANSPORT=http PORT=3000 node dist/index.js

Or using npm script

npm run start:http

The server will listen on http://0.0.0.0:3000/mcp.

3. Set up Nginx reverse proxy with TLS

server {

listen 443 ssl; server_name mcp.yourdomain.com;

ssl_certificate /etc/letsencrypt/live/mcp.yourdomain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/mcp.yourdomain.com/privkey.pem;

location /mcp { proxy_pass http://127.0.0.1:3000/mcp; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme;

Required for SSE streaming

proxy_set_header Connection ''; proxy_buffering off; proxy_cache off; chunked_transfer_encoding on; } }

Get a free TLS certificate:

sudo apt install certbot python3-certbot-nginx

sudo certbot --nginx -d mcp.yourdomain.com

4. Keep it running with systemd

Create /etc/systemd/system/youtube-mcp.service:

[Unit]

Description=YouTube MCP Server After=network.target

[Service] Type=simple User=your_user WorkingDirectory=/path/to/youtube-mcp ExecStart=/usr/bin/node dist/index.js --http Restart=always RestartSec=5 Environment=TRANSPORT=http Environment=PORT=3000 Environment=HOST=127.0.0.1

[Install] WantedBy=multi-user.target

sudo systemctl daemon-reload

sudo systemctl enable youtube-mcp sudo systemctl start youtube-mcp sudo systemctl status youtube-mcp

5. Connect MCP clients to your VPS

GitHub Copilot (VS Code) — Remote

{

"mcp": { "servers": { "youtube": { "type": "http", "url": "https://mcp.yourdomain.com/mcp" } } } }

Claude Desktop — Remote

{

"mcpServers": { "youtube": { "type": "streamable-http", "url": "https://mcp.yourdomain.com/mcp" } } }

Usage Examples

Once connected, you can ask your AI agent things like:

• *"Get info about this YouTube video: https://www.youtube.com/watch?v=dQw4w9WgXcQ"*
• *"Show me the top comments on video ID abc123"*
• *"Get the transcript of this video in English"*
• *"Summarize the transcript of https://youtu.be/xyz789"*
• *"Search for Node.js tutorials uploaded this week, sorted by views"*
• *"Find the most popular React videos from the last month"*

Tool Response Format

All tools return:

• content: short human-readable text for chat-style MCP clients
• structuredContent: JSON-shaped data for agents that need reliable fields

The server is intentionally JSON-first, text-second. Agents should prefer structuredContent when they need to filter, transform, or chain tool results.

Example shape from get_video_info:

{

"content": [ { "type": "text", "text": "📹 Example title\n\nChannel: Example channel\n..." } ], "structuredContent": { "videoId": "dQw4w9WgXcQ", "title": "Example title", "description": "Example description", "channelName": "Example channel", "channelId": "UC123", "uploadedAt": "Sep 14, 2017", "duration": "3m 33s", "durationSeconds": 213, "viewCount": "123456", "likeCount": "7890", "commentCount": null, "tags": ["music", "pop"], "thumbnailUrl": "https://..." } }

Values YouTube did not provide are null, never placeholders such as "0", "N/A" or "Unknown".

Errors

Failures return isError: true. The text starts with a code (❌ [ACCESS_BLOCKED] ...) and _meta["youtube-mcp/error"] carries the details:

{

"isError": true, "content": [{ "type": "text", "text": "❌ [ACCESS_BLOCKED] YouTube requires sign-in to access video C7OQHIpDlvA: Sign in to confirm you’re not a bot" }], "_meta": { "youtube-mcp/error": { "code": "ACCESS_BLOCKED", "message": "...", "retryable": false, "upstream": { "playabilityStatus": "LOGIN_REQUIRED", "reason": "Sign in to confirm you’re not a bot", "accessKind": "login_required" } } } }

The error is in _meta, not structuredContent, because MCP SDK clients validate any structuredContent against the tool's output schema, even on error results.

| VIDEO_UNAVAILABLE | YouTube reports the video as ERROR, UNPLAYABLE, private or offline. upstream.reason is