YouTube Music MCP Server

A production-grade Model Context Protocol (MCP) server that connects YouTube Music to AI assistants like Claude.
Implements the full MCP primitive set — Tools, Resources, and Prompts — for genuine agentic music experiences.

Architecture • Features • Installation • Authentication • Usage • Tools • Resources • Prompts

Architecture

┌────────────────────────────────────────────────────────────┐
│                    Claude / AI Assistant                   │
└──────────────────────┬─────────────────────────────────────┘
                       │  Model Context Protocol (stdio)
┌──────────────────────▼─────────────────────────────────────┐
│                 YouTube Music MCP Server v2                │
│                                                            │
│  ┌─────────────┐  ┌───────────────┐  ┌──────────────────┐  │
│  │  15 Tools   │  │  3 Resources  │  │    3 Prompts     │  │
│  │             │  │               │  │                  │  │
│  │ search      │  │library://     │  │weekly-discovery  │  │
│  │ stats       │  │  songs        │  │mood-based-       │  │
│  │ similar ★   │  │  artists      │  │  playlist        │  │
│  │ recommend ★ │  │  playlists    │  │artist-deep-dive  │  │
│  │ smart pl ★  │  └───────────────┘  └──────────────────┘  │
│  │ charts      │                                           │
│  │ insights    │  ┌───────────────────────────────────┐    │
│  │ moods       │  │  TTL Cache (5 min)  •  Async ★    │    │
│  │ ...         │  │  Custom Exceptions  •  Logging    │    │
│  └─────────────┘  └───────────────────────────────────┘    │
└──────────────────────┬─────────────────────────────────────┘
                       │  ytmusicapi
┌──────────────────────▼─────────────────────────────────────┐
│                   YouTube Music API                        │
└────────────────────────────────────────────────────────────┘
★ = Agentic / async feature

Related MCP server: YouTube Music MCP

Features

15 Tools · 3 Resources · 3 Prompts — full MCP primitive coverage:

🛠️ Tools

📦 Resources (passively readable by Claude)

💬 Prompts (guided conversation starters)

Installation

Prerequisites

• Python 3.10 or higher

• A YouTube Music account

• Browser developer tools access (for authentication)

Setup

1. Clone the repository

git clone https://github.com/codeRisshi25/youtubemusic-mcp.git
cd youtubemusic-mcp

2. Create virtual environment

python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# OR
venv\Scripts\activate     # Windows

3. Install dependencies

pip install -e .

Authentication

Choose one authentication method:

Option A: Cookie File (Simplest — recommended)

1. Visit music.youtube.com and log in

2. Open Developer Tools (F12)

3. Go to Network tab and refresh the page

4. Click any request → Headers → copy the full cookie: value

5. Paste it into a file named cookie.txt in the project directory

6. Done! The server auto-generates browser.json on first startup

# Optional: validate cookies before starting the server
python update_auth.py

Note: Cookies typically last 6–24 months. When they expire, just paste fresh cookies into cookie.txt and restart.

Option B: OAuth (Long-term)

See docs/OAUTH_SETUP.md for complete OAuth setup instructions.

Usage

Test with MCP Inspector

npx @modelcontextprotocol/inspector venv/bin/python server.py

Opens web interface at http://localhost:6274 to test all 15 tools, 3 resources, and 3 prompts.

Claude Desktop Integration

1. Config file location:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add configuration:

{
  "mcpServers": {
    "youtube-music": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/server.py"]
    }
  }
}

3. Restart Claude Desktop

See docs/CLAUDE_SETUP.md for detailed instructions.

Available Tools

See the Features section above for a full table of all 15 tools.

Agentic Highlights

build_smart_playlist — the centrepiece agentic tool. Runs a 6-step pipeline inside a single tool call:

Step 1: Fetch all Moods & Genres from YouTube Music
Step 2: Match your mood keyword to a real category
Step 3: Pull mood playlist pool from that category
Step 4: Sample tracks across multiple playlists
Step 5: Apply energy-level filter (high/medium/low)
Step 6: Optionally create & save to YouTube Music

find_similar_songs — uses get_watch_playlist(radio=True), the actual YTMusic similarity engine, not a fake artist search.

get_recommendations — fetches from 5 artists using asyncio.gather() for true parallel execution.

Running Tests

pip install -e ".[dev]"
pytest tests/ -v

51 tests covering auth, caching, all tools, resources, prompts, and routing — no network required (fully mocked).

Troubleshooting

Authentication Errors

If you get authentication errors after ~6 months:

1. Your cookies have likely expired

2. Follow the simple update process in docs/AUTH_UPDATE.md

3. You'll just need to paste fresh cookies from your browser

Server Not Detected in Claude

• Use absolute paths in claude_desktop_config.json

• Restart Claude Desktop after config changes

• Check logs in Claude → Help → View Logs

Import Errors

• Ensure virtual environment is activated

• Run pip install -e . in the project directory

Server Crashes on Startup

• Verify browser.json or oauth.json exists

• Check file permissions

• See docs/CLAUDE_SETUP.md for detailed troubleshooting

Contributing

See docs/CONTRIBUTING.md for contribution guidelines.

License

MIT License - see LICENSE

Copyright (c) 2025 Risshi Raj Sen

Links

• GitHub Issues

• Discussions

Built with ytmusicapi • MCP

⭐ Star if useful!