YouTube MCP Server

How to use

You run this MCP server in your environment and connect to it with an MCP client. The server exposes seven tools that return structured data (and one tool that returns a text transcript when requested). You control data exposure with safe defaults, and you can enable more expensive operations only when you truly need them.

Key capabilities include resolving a channel reference to a channel object, listing channel videos and playlists, listing videos within a playlist, performing channel-scoped keyword searches, and fetching public comment threads for a video. Use these tools to build features such as channel dashboards, video catalogs, playlist analyzers, and rich content pipelines.

How to install

Follow these concrete steps to install and run the MCP server in your environment. Choose the installation method that fits your workflow.

Prerequisites you must ensure are available on your system path:

Option 1 — pipx (zero local project setup, recommended for MCP hosts)

{
  "mcpServers": {
    "youtube_mcp": {
      "command": "pipx",
      "args": ["run", "--spec", "glonorce-youtube-mcp", "youtube_mcp"],
      "env": {
        "YOUTUBE_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Option 2 — pip into a dedicated virtual environment (no repo clone)

Create and activate a virtual environment, then install the MCP package.

python -m venv .venv_youtube_mcp
# Windows: .venv_youtube_mcp\Scripts\activate
# macOS/Linux: source .venv_youtube_mcp/bin/activate

python -m pip install -U pip
python -m pip install glonorce-youtube-mcp

MCP host configuration when using a pip-installed package

{
  "mcpServers": {
    "youtube_mcp": {
      "command": "youtube_mcp",
      "env": {
        "YOUTUBE_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Option 3 — local clone (development)

Clone the repository, set up a virtual environment, and install dependencies in editable mode.

git clone https://github.com/glonorce/youtube_mcp.git
cd youtube_mcp

python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate

python -m pip install -e .

Getting Your YouTube API Key

If you want to access additional data or use restricted endpoints, you can obtain a YouTube Data API v3 key. Store the key securely and provide it to the MCP host via environment variables in your configuration.

Notes on starting the MCP server

After you set up your environment and environment variables, start the MCP host as configured by your chosen option. The server will expose the seven tools described in the Tools section.

Security and maintenance

Protect your API key by avoiding exposure in version control. Use environment variables to supply secrets, and restrict your API key to the YouTube Data API. Monitor quota usage in your cloud provider’s console to prevent unexpected costs.

Example MCP calls

You can issue tool requests to the MCP server via your MCP client to resolve channels, list videos, and more. Each request uses the tool name and a structured argument set specific to that tool.

Troubleshooting and tips

If you encounter issues with missing tools, ensure you are running the latest editable installation or re-install with the chosen method. If your API key placeholder is not expanded, provide a real key in the host configuration.

Examples of usage patterns

- Resolve a channel to a detailed channel object, including uploads if requested.

- List a channel’s videos and playlists with pagination and safe defaults that exclude shorts and live streams unless explicitly enabled.

Technical notes

All tools except get_yt_video_info return structured JSON and include AI-friendly docstrings for easy integration. The server is designed to be quota-aware and safe-by-default.

get_yt_video_info

Fetches video metadata and transcript (when available) for a given video ID or URL.

resolve_youtube_channel

Resolves a channel reference to a structured channel object with metadata.

list_youtube_channel_videos

Lists videos in a channel with pagination and optional filters.

list_youtube_channel_playlists

Lists playlists in a channel with pagination.

list_youtube_playlist_videos

Lists videos within a playlist with pagination.

search_youtube_channel_videos

Performs a channel-scoped keyword search using the YouTube Search API; this is quota-expensive.

list_youtube_video_comments

Fetches public comment threads for a video with pagination.