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)
4. Create OAuth client ID:
   • Application type: Desktop app
   • Name: YouTube Music MCP (or any name)
5. 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

2. 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

3. Set environment variable:

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

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

5. 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