youtube-music-mcp-server by CaullenOmdahl - MCP Server

YouTube Music MCP Server

Full-featured MCP server for YouTube Music — search, manage playlists, and create smart recommendations through AI assistants.

Highlights

Complete Playlist Control — Create, edit, delete playlists with batch operations
Smart Recommendations — AI-driven playlist creation using ListenBrainz (unbiased, no payola)
Rich Metadata — Every response includes artist, album, year, and duration
Secure Auth — OAuth 2.1 + PKCE with encrypted token storage
Rate Limited — Configurable limits to respect API quotas

Quick Start

npm install
cp .env.example .env
# Add your Google OAuth credentials to .env
npm run build
npm start

MCP Configuration

{
  "mcpServers": {
    "youtube-music": {
      "command": "node",
      "args": ["path/to/youtube-music-mcp-server/dist/index.js"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id",
        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Tools

Search & Discovery

Tool	Description
`search_songs`	Search songs with configurable limits
`search_albums`	Search albums
`search_artists`	Search artists
`get_song_info`	Detailed song information
`get_album_info`	Album with all tracks
`get_artist_info`	Artist with top songs
`get_library_songs`	User's liked music (filters non-music)

Playlist Management

Tool	Description
`get_playlists`	List user's playlists
`get_playlist_details`	Playlist with all tracks
`create_playlist`	Create new playlist
`edit_playlist`	Update metadata
`delete_playlist`	Delete playlist
`add_songs_to_playlist`	Batch add songs
`remove_songs_from_playlist`	Batch remove songs

Smart Playlists

Tool	Description
`start_smart_playlist`	Begin creation session
`add_seed_artist`	Add artist influence
`add_seed_track`	Add track as seed
`refine_recommendations`	Set preferences (exclude, tags, diversity)
`get_recommendations`	Generate recommendations
`preview_playlist`	Preview before creating
`create_smart_playlist`	Create on YouTube Music
`get_user_taste_profile`	Analyze listening habits

Response Format

All tools return structured JSON with metadata:

{
  "songs": [{
    "videoId": "abc123",
    "title": "Song Title",
    "artists": [{"id": "...", "name": "Artist"}],
    "album": {"id": "...", "name": "Album", "year": 2023},
    "duration": "3:45",
    "durationSeconds": 225
  }],
  "metadata": {
    "returned": 20,
    "hasMore": true
  }
}

Example Workflows

"Make me a playlist based on Radiohead and Boards of Canada"

→ start_smart_playlist()
→ add_seed_artist("Radiohead")
→ add_seed_artist("Boards of Canada")
→ get_recommendations()
→ create_smart_playlist("Late Night Electronica")

"Add these songs to my workout playlist"

→ search_songs("high energy workout")
→ add_songs_to_playlist(playlistId, [videoId1, videoId2, ...])

Architecture

src/
├── index.ts              # Entry point
├── server.ts             # MCP server setup
├── youtube-music/        # Custom YTM client
│   ├── client.ts         # API methods
│   └── parsers.ts        # Response parsing
├── musicbrainz/          # MusicBrainz integration
├── listenbrainz/         # ListenBrainz recommendations
├── recommendations/      # Smart playlist engine
├── auth/                 # OAuth 2.1 + PKCE
└── tools/                # MCP tool definitions

Docker

docker build -t youtube-music-mcp .
docker run -p 8081:8081 \
  -e GOOGLE_OAUTH_CLIENT_ID="..." \
  -e GOOGLE_OAUTH_CLIENT_SECRET="..." \
  youtube-music-mcp

Development

npm run dev                           # Development mode
BYPASS_AUTH_FOR_TESTING=true npm run dev  # Skip OAuth for testing

License

MIT

CaullenOmdahl/youtube-music-mcp-server