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.

Website: zubeidhendricks.github.io/youtube-mcp-server

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.

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}"
      }
    }
  }
}

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

Contributing

See CONTRIBUTING.md for information about contributing to this repository.

License

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