youtube-complete-mcp 0.1.0

MCP server for YouTube Data, Analytics, and Reporting API workflows

youtube-mcp

An MCP server that exposes Google's three YouTube APIs (Data v3, Analytics v2, Reporting v1) as agent-callable tools. Built for AI assistants that need to inspect channels, fetch analytics, post comments, schedule live broadcasts, or upload videos without juggling raw OAuth refresh logic.

This server is a thin, opinionated wrapper around the official Google API client. It does not invent endpoints, hide quota costs, or try to be "smart" about the underlying API. What it does provide is brand-account-aware authentication, structured per-tool quota tracking, and an explicit safety policy that keeps destructive operations out of an agent's reach.

Features

1. Three API surfaces, one server. YouTube Data API v3, YouTube Analytics API v2, and YouTube Reporting API v1 are exposed side by side. Tool names use the youtube_*, analytics_*, and reporting_* prefixes so an agent can route by surface.
2. Multi-brand-account first-class. Each operator-configured account is keyed locally (for example main-channel, backup-channel) and OAuth tokens are kept per key. Agents pass account="main-channel" on every call.
3. OS keyring for tokens. Refresh and access tokens live in the system keyring (macOS Keychain, Windows Credential Locker, freedesktop Secret Service). Tokens never sit in plaintext config files.
4. Quota tracking per account. Every tool declares its quota cost. The server tracks daily usage per account key and exposes it through the youtube://quota/{account_key} resource.
5. Mutating-op guard. Mutating tools (uploads, edits, comment posts, rating, abuse reports) are gated by an account-handle check. By default only @jsigvardt may run mutating operations against live YouTube. See INSTALL.md for the override.
6. Operator CLI. youtube-mcp serve, youtube-mcp auth add, youtube-mcp auth list, youtube-mcp auth refresh, youtube-mcp status, youtube-mcp doctor, and youtube-mcp tools list cover the day-to-day setup and health-check loop.
7. Skill bundle for agents. A drop-in Claude skill bundle lives at skills/youtube-mcp/. Point your agent at it to teach the model when to use the server, which tool to pick, and how much quota each call costs.

Safety Policy: videos.delete is NOT a tool

The YouTube Data API endpoint videos.delete is deliberately excluded from this server. No tool wraps it. The youtube_videos_* module exposes list, insert, update, rate, getRating, and reportAbuse only.

The rationale is simple. Video deletion is irreversible at the API layer, and a bad agent prompt should never be one tool call away from wiping a channel's catalogue. If you need to take down a video, do it in the YouTube Studio UI. If you have a legitimate, audited workflow that requires programmatic deletion, fork this repo and add the tool yourself, with your own approval pipeline. We will not ship it upstream.

This rule is enforced both at the source level (no videos_delete symbol exists anywhere in src/) and by a CI grep that fails the build if the string ever appears.

Install

Requires Python 3.11 or 3.12 and uv.

The PyPI distribution name is youtube-complete-mcp. The shorter youtube-mcp package name is already occupied by an unrelated transcript package, so do not install it expecting this server.

Run the published server with uvx:

uvx youtube-complete-mcp --help
uvx youtube-complete-mcp serve --transport stdio

The wheel also installs a youtube-mcp console alias for persistent virtual environments. With uvx, prefer the distribution-matched youtube-complete-mcp command above. If a client must call the historical executable name, use uvx --from youtube-complete-mcp youtube-mcp serve --transport stdio.

For local development from a clone:

git clone https://github.com/sigvardt/youtube-mcp.git
cd youtube-mcp
uv sync
uv run youtube-mcp --help

OAuth setup, GCP project configuration, and the brand-account picker step are covered in INSTALL.md. Read it before the first youtube-complete-mcp auth add.

Quickstart

1. Follow INSTALL.md to create a GCP OAuth client and add at least one account.

2. Verify the install:

   uvx youtube-complete-mcp status
   uvx youtube-complete-mcp tools list --api youtube
   

3. Wire the server into your MCP client.

Claude Desktop

Edit claude_desktop_config.json (location varies per OS; see the Anthropic docs):

{
  "mcpServers": {
    "youtube-mcp": {
      "command": "uvx",
      "args": ["youtube-complete-mcp", "serve", "--transport", "stdio"]
    }
  }
}

If you cloned the repo instead of installing the published wheel, point command at uv and args at ["--directory", "/abs/path/to/youtube-mcp", "run", "youtube-mcp", "serve"].

OpenCode

In your OpenCode config:

{
  "mcp": {
    "youtube-mcp": {
      "type": "local",
      "command": ["uvx", "youtube-complete-mcp", "serve", "--transport", "stdio"],
      "enabled": true
    }
  }
}

Other MCP clients

The server speaks the standard MCP protocol over stdio (default), HTTP, or SSE. Pick the transport that matches your client:

uvx youtube-complete-mcp serve --transport stdio
uvx youtube-complete-mcp serve --transport http --host 127.0.0.1 --port 8765
uvx youtube-complete-mcp serve --transport sse --host 127.0.0.1 --port 8765

Tool inventory

There are 17 tool modules under src/youtube_mcp/tools/. Run uvx youtube-complete-mcp tools list for the live list with quota costs and descriptions. The modules group as follows:

1. Data API v3 (read/write): activities, captions, channel_sections, channels, comment_threads, comments, i18n, live_chat, livestream, members, misc, playlists, search, subscriptions, super_chat_events, video_assets, video_meta, videos.
2. Analytics API v2: analytics_groups, analytics_reports.
3. Reporting API v1: reporting_jobs, reporting_reports.

Every tool returns a structured Pydantic model. None return raw HTTP bodies.

Resources

The server also exposes three MCP resources:

1. youtube://accounts: list of configured account keys, handles, channel IDs, and granted scopes. Never includes tokens.
2. youtube://quota/{account_key}: current daily quota usage for a key.
3. youtube://status: version, transport, and configured account count.

For agents and skill authors

The skill bundle at skills/youtube-mcp/ is the canonical "when to use this server" reference for AI assistants. It explains:

1. Which API to pick for a given question (Data vs Analytics vs Reporting).
2. The brand-account model and how to pass account="<key>".
3. Quota cost per tool and how to budget.
4. Workflow guides for upload, comment moderation, live broadcast, and analytics pulls.

If you are building a Claude skill or OpenCode agent on top of this server, ingest the skill bundle. Do not re-derive the catalogue from tools list output alone.

Working on the code

See CLAUDE.md for project conventions, the module map, the "where do I add a new tool" guide, and the mutating-guard rationale. New contributors and AI assistants editing this repo should read it first.

License

MIT. See LICENSE.