Axiom Works YouTube + YouTube Music MCP Server

The definitive MCP server for YouTube and YouTube Music. 68 tools across search, playlists, comments, analytics, live streaming, and full YouTube Music library management.

No other YouTube MCP server covers analytics, live streaming, comments (write), video uploads, or YouTube Music. This one covers all of them.

Quick Start

# Install
pip install axiomworks-youtube-mcp

# Or run directly with uvx (zero install)
uvx axiomworks-youtube-mcp run

Add to Claude Code

{
  "mcpServers": {
    "youtube": {
      "command": "uvx",
      "args": ["axiomworks-youtube-mcp", "run"]
    }
  }
}

Add to Claude Desktop

{
  "mcpServers": {
    "youtube": {
      "command": "uvx",
      "args": ["axiomworks-youtube-mcp", "run"]
    }
  }
}

Setup

The server works immediately with zero configuration (Tier 0). Add credentials to unlock more features:

axiomworks-youtube-mcp setup

Getting an API Key (Tier 1)

1. Go to Google Cloud Console
2. Create a project (or use an existing one)
3. Enable YouTube Data API v3
4. Create an API key
5. Run axiomworks-youtube-mcp setup and paste the key

Setting Up OAuth (Tier 2)

YouTube OAuth (likes, comments, uploads, analytics):

1. In Google Cloud Console, create OAuth 2.0 Client ID (Desktop application)
2. Configure the OAuth consent screen (External, Testing mode, add your email as test user)
3. Download the client secrets JSON file
4. Place it at ~/.config/axiomworks-youtube-mcp/client_secrets.json
5. Run axiomworks-youtube-mcp setup and follow the OAuth flow

YouTube Music OAuth (library, history, playlists):

1. Create a second OAuth client — type: TVs and Limited Input devices
2. Download the JSON and place it at ~/.config/axiomworks-youtube-mcp/client_secrets_tv.json
3. Run axiomworks-youtube-mcp setup — Step 3 will use the TV client for YouTube Music's device code flow

Tools (68 total)

YouTube Search & Discovery (3 tools)

Video Operations (8 tools)

Channel Operations (6 tools)

Playlist Operations (7 tools)

Comments (7 tools)

Analytics (5 tools)

Live Streaming (3 tools)

YouTube Music — Search & Browse (11 tools)

YouTube Music — Library (9 tools)

YouTube Music — Playlists (6 tools)

YouTube Music — Podcasts (3 tools)

Quota Management

The YouTube Data API has a 10,000 units/day quota. This server includes built-in quota tracking:

• Warnings at 80% usage (8,000 units)
• Errors at 100% to prevent failed API calls
• Quota resets daily at midnight Pacific Time
• YouTube Music tools use a separate internal API and are not subject to this quota

Response Caching

Repeated queries are served from a local SQLite cache to reduce quota usage:

API Gaps

Some YouTube features are not available through any official API. See API_GAPS.md for a comprehensive list of limitations and our recommendations to YouTube for improvement.

Key gaps: no watch history API, no YouTube Shorts-specific endpoints, no YouTube Music official API, no playback control.

Development

# Clone
git clone https://github.com/axiomworks-ai/axiomworks-youtube-mcp.git
cd axiomworks-youtube-mcp

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/

# Type check
mypy src/

Architecture

src/axiomworks_youtube_mcp/
├── server.py          # MCP server + 68 tool definitions
├── config.py          # Configuration and auth tier management
├── cli.py             # CLI: setup, status, run, version
├── clients/
│   ├── youtube.py     # YouTube Data API v3 client
│   ├── ytmusic.py     # YouTube Music client (ytmusicapi)
│   ├── analytics.py   # YouTube Analytics API client
│   └── live.py        # YouTube Live Streaming client
└── utils/
    ├── cache.py       # Response caching (SQLite)
    └── quota.py       # Daily quota tracking and warnings

Comparison

License

Apache License 2.0 — Free to use, modify, and distribute. Attribution required.

Copyright 2026 Axiom Works AI

Documentation

• User Guide — Use cases, creative examples, tips
• API Gaps — YouTube API limitations and upstream feedback
• Upstream Contributions — ytmusicapi PR targets
• Changelog — Version history

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Areas where help is especially valued:

• Additional YouTube Music features via ytmusicapi upstream contributions
• Test coverage
• Documentation and examples
• Integration guides for different MCP clients