YouTube MCP Server

A Model Context Protocol (MCP) server implementation for YouTube, enabling AI language models to interact with YouTube content through a standardized interface.

Available Tools

The server currently exposes 10 MCP tools.

Tool Parameters

videos_getVideo

• videoId (string): The YouTube video ID.
• parts (string[], optional): Specific video resource parts to retrieve.

videos_searchVideos

• query (string): Search query.
• maxResults (number, optional): Maximum number of results to return.
• order (string, optional): Result ordering such as relevance or date.
• publishedAfter (string, optional): Only include videos published after this ISO 8601 date.
• publishedBefore (string, optional): Only include videos published before this ISO 8601 date.
• channelId (string, optional): Restrict results to a specific channel.
• uniqueChannels (boolean, optional): Return only one video per unique channel.
• channelMinSubscribers / channelMaxSubscribers (number, optional): Filter matched videos by the subscriber band of their channel.
• channelLastUploadAfter / channelLastUploadBefore (string, optional): Filter matched videos by the latest upload activity of their channel.
• creatorOnly (boolean, optional): Restrict results to channels heuristically classified as creators.
• sortBy (string, optional): Supports relevance, subscribers_asc, subscribers_desc, indie_priority, and recent_activity.

transcripts_getTranscript

• videoId (string): The YouTube video ID.
• language (string, optional): Transcript language code. Falls back to YOUTUBE_TRANSCRIPT_LANG or en.

channels_getChannel

• channelId (string): The YouTube channel ID.

Responses now include:

• latestVideoPublishedAt
• normalizedMetadata
  • includes country, defaultLanguage, joinedAt, customUrl, emailsFound, contactLinks, and creator-vs-brand heuristic fields

channels_getChannels

• channelIds (string[]): A list of YouTube channel IDs.
• includeLatestUpload (boolean, optional): Whether to include latestVideoPublishedAt. Defaults to true.

channels_searchChannels

• query (string): Channel search query or handle.
• maxResults (number, optional): Maximum number of channels to return.
• order (string, optional): Result ordering such as relevance.
• channelType (string, optional): Restrict the search to a channel type.
• minSubscribers / maxSubscribers (number, optional): Filter channels by subscriber band.
• lastUploadAfter / lastUploadBefore (string, optional): Filter channels by latest upload activity.
• creatorOnly (boolean, optional): Restrict results to channels heuristically classified as creators.
• sortBy (string, optional): Supports relevance, subscribers_asc, subscribers_desc, indie_priority, and recent_activity.

channels_findCreators

• query (string): Topic, game, or mention query to discover channels from matched videos.
• videoPublishedAfter / videoPublishedBefore (string, optional): Recency filters for the matched videos.
• channelMinSubscribers / channelMaxSubscribers (number, optional): Subscriber band filters for returned channels.
• channelLastUploadAfter / channelLastUploadBefore (string, optional): Latest-upload activity filters for returned channels.
• creatorOnly (boolean, optional): Restrict results to channels heuristically classified as creators.
• sortBy (string, optional): Supports relevance, subscribers_asc, subscribers_desc, indie_priority, and recent_activity.
• sampleVideosPerChannel (number, optional): How many matched videos to include per returned channel.

channels_listVideos

• channelId (string): The YouTube channel ID.
• maxResults (number, optional): Maximum number of videos to return.

playlists_getPlaylist

• playlistId (string): The YouTube playlist ID.

playlists_getPlaylistItems

• playlistId (string): The YouTube playlist ID.
• maxResults (number, optional): Maximum number of playlist items to return.

Development

# Install dependencies
npm install

# Build
npm run build

# Start the server (requires at least one configured YouTube API key)
npm start

# Development mode with auto-rebuild
npm run dev

Docker

The included Docker image starts the server over HTTP by default.

• Default transport: http
• Default endpoint: http://localhost:8088/mcp
• Readiness endpoint: http://localhost:8088/ready
• Default mode: stateless

The Docker build copies .env into the runtime image and the server loads it automatically on startup. That means the container can run without passing API credentials at docker run time, as long as .env was present during docker build.

docker build -t youtube-mcp-server .
docker run --rm -p 8088:8088 youtube-mcp-server

The container defaults to:

MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=8088
MCP_STATELESS=true

Installation

Quick Setup for Claude Desktop

1. Install the package:

npm install -g zubeid-youtube-mcp-server

2. Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "zubeid-youtube-mcp-server": {
      "command": "zubeid-youtube-mcp-server",
      "env": {
        "YOUTUBE_API_KEY": "your_primary_youtube_api_key",
        "YOUTUBE_API_KEY2": "your_secondary_youtube_api_key",
        "YOUTUBE_API_KEY3": "your_tertiary_youtube_api_key"
      }
    }
  }
}

Alternative: Using NPX (No Installation Required)

Add this to your Claude Desktop configuration:

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "zubeid-youtube-mcp-server"],
      "env": {
        "YOUTUBE_API_KEY": "your_primary_youtube_api_key",
        "YOUTUBE_API_KEY2": "your_secondary_youtube_api_key",
        "YOUTUBE_API_KEY3": "your_tertiary_youtube_api_key"
      }
    }
  }
}

Installing via Smithery

To install YouTube MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @ZubeidHendricks/youtube --client claude

Configuration

Set the following environment variables:

• YOUTUBE_API_KEY: Primary YouTube Data API key
• YOUTUBE_API_KEY2: Secondary fallback API key
• YOUTUBE_API_KEY3: Third fallback API key
• YOUTUBE_TRANSCRIPT_LANG: Default language for transcripts (optional, defaults to 'en')

At least one of YOUTUBE_API_KEY, YOUTUBE_API_KEY2, or YOUTUBE_API_KEY3 must be set. When a request fails because a key has exhausted its quota, the server retries the same request with the next configured key.

Using with VS Code

For one-click installation, click one of the install buttons below:

Manual Installation

If you prefer manual installation, first check the install buttons at the top of this section. Otherwise, follow these steps:

Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "YouTube API Key",
        "password": true
      }
    ],
    "servers": {
      "youtube": {
        "command": "npx",
        "args": ["-y", "zubeid-youtube-mcp-server"],
        "env": {
          "YOUTUBE_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

Optionally, you can add it to a file called .vscode/mcp.json in your workspace:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "YouTube API Key",
      "password": true
    }
  ],
  "servers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "zubeid-youtube-mcp-server"],
      "env": {
        "YOUTUBE_API_KEY": "${input:apiKey}"
      }
    }
  }
}

License

This project is licensed under the MIT License - see the LICENSE file for details.