youtube-mcp-full

A Model Context Protocol (MCP) server that provides near 1:1 coverage of the YouTube Data API v3, YouTube Analytics API, and YouTube Reporting API as MCP tools for AI agents such as opencode, Claude, Cursor and any other MCP client.

Search videos, read channel stats, query analytics, manage playlists, read comments, pull reporting data — all directly from your agent with a single server that covers all three YouTube API surfaces.

Table of Contents

• Why another YouTube MCP server?
• What it provides
• Getting started
  • Prerequisites
  • 1. Install
  • 2. Configure credentials
  • 3. Register with your MCP client
• Prompt examples
• Tool reference
• Data & safety notes
• Contributing
• Limitations
• Support
• License

Why another YouTube MCP server?

Three other YouTube MCP servers exist:

• kimtaeyoon83/mcp-server-youtube-transcript — 592 ★, focused on transcript/subtitle extraction only
• ZubeidHendricks/youtube-mcp-server — 568 ★, 10 tools covering search and basic read operations
• pauling-ai/youtube-mcp-server — 19 ★, 40 tools with broad but early-stage coverage

All are good projects and I have no affiliation with them — they are referenced here for honest comparison. They primarily focus on the transcript or read/search surface of the YouTube Data API.

This project deliberately goes further:

Key differentiators:

• Full three-API coverage. The only YouTube MCP server that covers Data API v3, Analytics API, and Reporting API in a single server. Analytics queries (views, likes, watch time by day/video/country) and Reporting jobs (automated daily CSV reports) are not available in any other YouTube MCP project.
• Two tool layers. 99 auto-generated 1:1 endpoint tools guarantee no API method is missed, while 16 typed convenience tools provide ergonomic access to the most common operations with sensible defaults and proper type hints.
• OAuth support. Enables write operations (upload, comment, rate) and Analytics/Reporting access that require user authorization — not just API key read-only access.
• Production infrastructure. Docker with HEALTHCHECK, optional HTTP transport with bearer token auth, OIDC trusted publishing (no PyPI token to manage), Trivy container scanning, and dependency audit in CI.

What it provides

A single stdio (or HTTP) MCP server exposing 115 tools (published on PyPI as youtube-mcp-full):

• Search — search_videos (keyword search with filters for channel, duration, date range, region, safe search)
• Videos — get_video (single video by ID), list_videos (chart-based: mostPopular, recent)
• Channels — get_channel (by ID, handle, or username), get_my_channel (authenticated user's channel)
• Playlists — list_playlists (by channel or authenticated user), list_playlist_items (videos in a playlist)
• Comments — list_comment_threads (top-level comments for a video/channel, with search), list_comments (replies to a thread)
• Analytics — analytics_query (views, likes, subscribers, watch time, revenue with dimensions and filters)
• Reporting — list_reporting_jobs, list_reporting_job_reports, list_report_types (automated daily report management)
• Subscriptions — list_subscriptions (authenticated user's subscriptions)
• Thumbnails — set_thumbnail (upload custom thumbnail)
• Video categories — list_video_categories (region-specific category IDs)
• Auth / meta — health, auth_status, list_supported_apis
• 99 generated endpoint tools — full 1:1 mapping of every YouTube API method with params_json/body_json interface for maximum flexibility

Getting started

Prerequisites

• Python 3.10+
• A Google Cloud project with YouTube Data API v3 enabled (and optionally Analytics + Reporting APIs)
• An MCP-capable client (opencode, Claude Desktop, Cursor, etc.)

1. Install

If you are using an AI coding client, a simple prompt is often enough to get started, for example: "Install the YouTube MCP as described in this GitHub repository oliverhruby/youtube-mcp". Most MCP-capable clients can then guide you through the available setup options.

Option A — from PyPI (recommended)

uvx youtube-mcp-full
# or, if you prefer pip:
pip install youtube-mcp-full

uvx runs the package without a persistent install. If uvx is unavailable, install uv first (pip install uv or winget install astral-sh.uv).

Option B — from GitHub (latest source)

uvx --from "git+https://github.com/oliverhruby/youtube-mcp.git" youtube-mcp-full
# or
pip install "git+https://github.com/oliverhruby/youtube-mcp.git"

Option C — development from source

git clone https://github.com/oliverhruby/youtube-mcp.git
cd youtube-mcp
uv sync
uv run youtube-mcp-full

Option D — Docker

Pull a prebuilt image (recommended):

docker pull ghcr.io/oliverhruby/youtube-mcp:latest

docker run --rm -i \
  -e YOUTUBE_API_KEY=your_api_key \
  ghcr.io/oliverhruby/youtube-mcp:latest

Build locally from source (fallback):

docker build -t youtube-mcp-full .

docker run --rm -i \
  -e YOUTUBE_API_KEY=your_api_key \
  youtube-mcp-full

The container uses the same environment variables described in Configure credentials. It includes a HEALTHCHECK for container orchestration.

For HTTP transports, set additional vars:

• MCP_TRANSPORT: stdio (default), sse, or streamable-http
• MCP_HOST: bind host (default 0.0.0.0)
• MCP_PORT: bind port (default 8000)
• MCP_API_KEY: optional bearer token for HTTP auth

When MCP_API_KEY is set, HTTP requests must include Authorization: Bearer <key>. If MCP_API_KEY is not set, HTTP endpoints are unauthenticated. For production, prefer proper authentication and TLS via a reverse proxy or API gateway.

pyproject.toml pins mcp<2 (the stable FastMCP v1 API).

2. Configure credentials

API key only (read-only access):

Get an API key from Google Cloud Console with YouTube Data API v3 enabled.

# Windows (persistent, per-user)
setx YOUTUBE_API_KEY "your_api_key"

# macOS / Linux
export YOUTUBE_API_KEY="your_api_key"

OAuth (full access including Analytics, Reporting, and write operations):

Create OAuth 2.0 credentials in Google Cloud Console with the YouTube Data API and YouTube Analytics API scopes. You'll need a client ID, client secret, and a refresh token.

# Windows
setx YOUTUBE_CLIENT_ID "your_client_id"
setx YOUTUBE_CLIENT_SECRET "your_client_secret"
setx YOUTUBE_REFRESH_TOKEN "your_refresh_token"

# macOS / Linux
export YOUTUBE_CLIENT_ID="your_client_id"
export YOUTUBE_CLIENT_SECRET="your_client_secret"
export YOUTUBE_REFRESH_TOKEN="your_refresh_token"

API key + OAuth: Both can be set. OAuth credentials take priority when present; API key is used as fallback for public endpoints.

3. Register with your MCP client

opencode — add to ~/.config/opencode/opencode.json (or opencode.jsonc):

{
  "mcp": {
    "youtube": {
      "type": "local",
      "enabled": true,
      "command": ["uvx", "youtube-mcp-full"],
      "env": {
        "YOUTUBE_API_KEY": "{env:YOUTUBE_API_KEY}"
      }
    }
  }
}

Put credentials in your shell/environment (or a .env) and reference them with {env:VAR}, or hardcode them under env: directly.

Claude Desktop / Cursor — use claude_desktop_config.json / .mcp.json with a mcpServers entry in the standard shape, pointing command/args at the venv python and the youtube_mcp path, plus an env block with your credentials.

After editing client config, restart the client so the MCP server is loaded.

Prompt examples

Tool reference

Convenience tools (16)

Generated endpoint tools (99)

Auto-generated 1:1 wrappers for every method in the YouTube Data API v3, Analytics API v2, and Reporting API v1. Each tool accepts params_json and body_json string arguments matching the REST API parameters.

Examples: youtube_data_v3_search_list, youtube_data_v3_videos_list, youtube_analytics_v2_reports_query, youtube_reporting_v1_jobs_list.

Run list_supported_apis to see the full count and per-API breakdown.

Meta tools

Data & safety notes

• API quotas. YouTube Data API has a default quota of 10,000 units/day per project. Search costs 100 units; video list costs 1 unit. Analytics and Reporting API calls have separate quotas. Monitor usage in Google Cloud Console.
• OAuth scopes. Write operations (upload, comment, rate) and Analytics access require OAuth with the appropriate scopes. API key access is read-only and limited to public data.
• Rate limiting. The YouTube API enforces per-second rate limits. The server does not add additional throttling — if you hit a rate limit, retry after the backoff period.
• Generated tools are raw. The 99 generated endpoint tools pass parameters as JSON strings. For ergonomic access, use the 16 convenience tools which have typed parameters and sensible defaults.

Contributing

Contributor and maintainer guidance is in CONTRIBUTING.md.

• Contribution workflow and local setup
• Architecture and tool layers
• Release process (PyPI, GitHub Releases, GHCR)
• CI quality gates and coverage drift checks

Limitations

• API quota dependent. YouTube enforces daily and per-second quotas. Heavy usage (especially search) can exhaust the daily quota quickly.
• OAuth complexity. Full Analytics/Reporting access requires OAuth 2.0 with refresh tokens, which involves creating credentials in Google Cloud Console and handling token refresh. API key access is simpler but read-only.
• No live streaming tools. The liveBroadcasts/liveStreams endpoints are generated but not wrapped with convenience tools — use the raw generated tools with params_json for live stream management.
• No video upload via convenience tool. Video upload requires multipart media upload which the generated tool layer handles at the REST level but is not exposed through a convenience tool yet.
• The server processes requests synchronously. Large analytics queries may take several seconds.

Support

If you like this project and want to support or request a feature, send me a beer, it keeps my mind relaxed and ideas will come :-)

License

MIT © Oliver Hrubý

YouTube is a trademark of Google LLC. This project is not affiliated with or endorsed by Google or YouTube.