YouTube Music MCP Server

Model Context Protocol server for YouTube Music integration. Allows AI assistants to search for music and create/manage playlists on your YouTube account.

Features

• Search for tracks on YouTube Music
• Create new playlists
• Add tracks to existing playlists
• Batch operations (search and add multiple tracks at once)
• List your library playlists
• OAuth 2.0 authentication with Google

Prerequisites

• Python 3.10+
• Google account with YouTube access
• Google Cloud project with YouTube Data API enabled

Setup

1. Create a Google Cloud Project

1. Go to Google Cloud Console
2. Create a new project (or select an existing one)
3. Enable the YouTube Data API v3:

• Go to APIs & Services → Library
• Search for "YouTube Data API v3"
• Click Enable

2. Create OAuth Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. If prompted, configure the OAuth consent screen:

• Choose External user type
• Fill in the required fields (app name, support email)
• Add scope: https://www.googleapis.com/auth/youtube
• Add your email as a Test user (required while in testing mode)

1. Create OAuth client ID:

• Application type: Desktop app
• Name: YouTube Music MCP (or any name)

1. Download the JSON file and save it as client_secret.json in the project root

3. Install the Server

# Clone the repository
git clone https://github.com/leosakharoff/youtube-music-mcp.git
cd youtube-music-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

4. Authenticate with Google

python -m src.auth

This opens a browser window for Google sign-in. After authorizing, your credentials are saved to token.json (gitignored).

Usage

Local Usage with Claude Desktop

Add to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Local Usage with Claude Code

claude mcp add youtube-music "python -m src.server" --cwd /path/to/youtube-music-mcp

Remote Deployment (Render)

Deploy to Render for use with Claude web/iOS without your computer running.

1. Fork this repository to your GitHub account

1. Create a new Web Service on Render:

• Connect your GitHub repo
• Build Command: pip install -r requirements.txt
• Start Command: python -m src.server_remote

1. Set environment variable:

• Generate base64 token: cat token.json | base64
• Add env var: YOUTUBE_TOKEN_B64 = (your base64 string)

1. Deploy! Your server will be at https://your-service.onrender.com

1. In Claude, add custom connector with URL: https://your-service.onrender.com/sse

Note: Render free tier sleeps after 15 min of inactivity. First request may take ~30s to wake up.

Example Prompts

Once connected to Claude, try:

• "Search YouTube Music for 'Neu! Hallogallo'"
• "Create a playlist called 'Krautrock Classics'"
• "Add these tracks to my playlist: 'Can Vitamin C', 'Kraftwerk Autobahn', 'Tangerine Dream Phaedra'"
• "Show me my YouTube playlists"

Available Tools

| Tool | Description | |------|-------------| | search_youtube_music | Search for tracks (returns videoId for adding to playlists) | | create_playlist | Create a new playlist (private, public, or unlisted) | | add_to_playlist | Add videos to an existing playlist | | get_my_playlists | List your YouTube playlists | | get_playlist_details | Get all tracks from a playlist | | search_and_add | Search for songs and add top results to a playlist | | update_playlist | Update playlist title and/or description | | delete_playlist | Delete a playlist (cannot be undone) |

Troubleshooting

"Access blocked" during OAuth

Your Google Cloud app is in testing mode. Add your email as a test user:

1. Go to APIs & Services → OAuth consent screen
2. Under Test users, click Add Users
3. Add your Google account email

Token refresh errors

Delete token.json and run python -m src.auth again.

Rate limiting

YouTube Data API has quotas. If you hit limits:

• Reduce batch sizes
• Wait before retrying
• Check your API quota

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Format code
black src/ tests/
ruff check src/ tests/

Security Notes

• client_secret.json and token.json contain sensitive credentials
• Both are gitignored by default - never commit them
• For remote deployment, use environment variables (base64 encoded)

License

MIT License

Acknowledgments

• Uses YouTube Data API v3
• Built with Model Context Protocol