🎵 ytm-mcp

A full-featured YouTube Music MCP server — control playback, browse history, download songs, manage playlists, and more from any AI assistant.

What is ytm-mcp?

ytm-mcp is a Model Context Protocol (MCP) server that gives AI assistants full control over YouTube Music. Connect it to Claude, Cursor, VS Code, or any MCP-compatible tool and control your music with natural language.

"What were my last 12 songs?"
"Download all my recent history as opus files"
"Play Stars Ultra Slowed and like it"
"Skip to the next track and turn the volume to 70"
"Create a playlist called Night Drive from my history"

✨ Features

Category	What you get
🎧 History	Scrape your full listening history with titles, artists, albums & URLs
🔍 Search	Search YouTube Music for any song, artist, or album
▶️ Playback	Play, pause, skip, seek, volume, like, shuffle, repeat
📥 Downloads	Download songs as Opus or MP3 via yt-dlp with embedded metadata & thumbnails
📋 Playlists	Create, edit, export local playlists as JSON or CSV
💾 Database	SQLite persistence — history, downloads, playlists all cached locally

🛠 Requirements

Node.js 18+
yt-dlp — for downloading songs
Python mutagen — for embedding metadata: pip install mutagen
Chrome or Chromium — must be logged into YouTube Music

🚀 Installation

# 1. Clone the repo
git clone https://github.com/4shil/ytm-mcp.git
cd ytm-mcp

# 2. Install dependencies
npm install

# 3. Build
npm run build

# 4. Configure
cp .env.example .env

Find your Chrome profile path

This is the folder where your browser stores your logged-in session.

Platform	Path
Linux (Chrome)	`~/.config/google-chrome/Default`
Linux (Chromium)	`~/.config/chromium/Default`
macOS (Chrome)	`~/Library/Application Support/Google/Chrome/Default`
Windows (Chrome)	`%LOCALAPPDATA%\Google\Chrome\User Data\Default`

⚠️ The profile must already be logged into YouTube Music. The server won't handle login — just reuse your existing session.

`.env` Configuration

# Your Chrome/Chromium profile path (see table above)
BROWSER_PROFILE=/path/to/your/chrome-profile

# Where downloaded songs are saved
DOWNLOAD_DIR=./downloads

# SQLite database location
DB_PATH=./db/ytm.db

🔌 Connect to Your AI Tool

mcporter CLI

Install mcporter and register ytm-mcp:

npm install -g mcporter
mcporter config add ytm-mcp --stdio "node /path/to/ytm-mcp/dist/index.js"

List all tools:

mcporter list ytm-mcp

Call tools directly from your terminal:

mcporter call ytm-mcp.get_history limit=12
mcporter call ytm-mcp.search_song query="Stars Ultra Slowed"
mcporter call ytm-mcp.download_song url="https://music.youtube.com/watch?v=4Z8LwuQ3zao"
mcporter call ytm-mcp.playback_control action=like
mcporter call ytm-mcp.get_current_song

Claude Desktop

Edit claude_desktop_config.json:

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

{
  "mcpServers": {
    "ytm-mcp": {
      "command": "node",
      "args": ["/path/to/ytm-mcp/dist/index.js"],
      "env": {
        "BROWSER_PROFILE": "/path/to/your/chrome-profile"
      }
    }
  }
}

Restart Claude Desktop. You'll see ytm-mcp in the tools list. ✅

OpenClaw

Add to ~/.openclaw/config.json:

{
  "mcp": {
    "servers": [
      {
        "name": "ytm-mcp",
        "command": "node",
        "args": ["/path/to/ytm-mcp/dist/index.js"],
        "env": {
          "BROWSER_PROFILE": "/path/to/your/chrome-profile"
        }
      }
    ]
  }
}

Or with mcporter:

mcporter add ytm-mcp --command "node /path/to/ytm-mcp/dist/index.js"

Cursor

Create or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ytm-mcp": {
      "command": "node",
      "args": ["/path/to/ytm-mcp/dist/index.js"],
      "env": {
        "BROWSER_PROFILE": "/path/to/your/chrome-profile"
      }
    }
  }
}

Antigravity

Create mcp.json in the Antigravity user config directory:

Linux: ~/.config/Antigravity/User/mcp.json
macOS: ~/Library/Application Support/Antigravity/User/mcp.json
Windows: %APPDATA%\Antigravity\User\mcp.json

{
  "servers": {
    "ytm-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/ytm-mcp/dist/index.js"],
      "env": {
        "BROWSER_PROFILE": "/path/to/your/chrome-profile"
      }
    }
  }
}

Reload Antigravity (Ctrl+Shift+P → Developer: Reload Window). ✅

VS Code (GitHub Copilot)

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "ytm-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/ytm-mcp/dist/index.js"],
      "env": {
        "BROWSER_PROFILE": "/path/to/your/chrome-profile"
      }
    }
  }
}

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "ytm-mcp": {
      "command": {
        "path": "node",
        "args": ["/path/to/ytm-mcp/dist/index.js"],
        "env": {
          "BROWSER_PROFILE": "/path/to/your/chrome-profile"
        }
      }
    }
  }
}

Continue.dev

Add to ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "node",
          "args": ["/path/to/ytm-mcp/dist/index.js"],
          "env": {
            "BROWSER_PROFILE": "/path/to/your/chrome-profile"
          }
        }
      }
    ]
  }
}

Any MCP Tool (Generic)

ytm-mcp uses standard stdio transport. Any MCP-compatible tool can connect:

Transport: stdio
Command:   node
Args:      ["/path/to/ytm-mcp/dist/index.js"]

🧰 Tools Reference

🎧 History

`get_history`

Scrape your YouTube Music listening history.

Parameter	Type	Default	Description
`limit`	number	`20`	Number of songs to fetch
`use_cache`	boolean	`false`	Return cached DB results (no browser)

get_history(limit: 12)
get_history(limit: 50, use_cache: true)

🔍 Search & Download

`search_song`

Search YouTube Music for songs.

Parameter	Type	Default	Description
`query`	string	required	Song, artist, or album name
`limit`	number	`5`	Max results to return

`download_song`

Download a single song by URL.

Parameter	Type	Default	Description
`url`	string	required	YouTube Music URL
`format`	string	`opus`	`opus` or `mp3`
`title`	string	—	Optional title hint

`download_history`

Batch download your recent listening history.

Parameter	Type	Default	Description
`limit`	number	`12`	Songs to download
`format`	string	`opus`	`opus` or `mp3`

`list_downloads`

List all downloaded files with sizes and timestamps.

▶️ Playback

`play_song`

Search and play a song, or play by direct URL.

Parameter	Type	Description
`query`	string	Search query (e.g. `"INSONAMIA ZYZZCVNT"`)
`url`	string	Direct YouTube Music URL

`playback_control`

Full playback control in one tool.

Action	Description
`play`	Resume playback
`pause`	Pause playback
`toggle`	Toggle play/pause
`next`	Next track
`previous`	Previous track
`shuffle`	Toggle shuffle
`repeat`	Cycle repeat mode
`like`	Like current song ❤️
`dislike`	Dislike current song
`volume`	Set volume (`volume: 80`)
`seek`	Seek to seconds (`seek: 45`)

`get_current_song`

Get the current now-playing state.

▶️ Stars (Ultra Slowed) — SCXR SOUL ❤️
⏱ 0:42 / 1:46 | 🔊 80%

📋 Playlists

`create_playlist`

Parameter	Type	Default	Description
`name`	string	required	Playlist name
`visibility`	string	`private`	`public` or `private`

`add_to_playlist`

Parameter	Type	Description
`playlist_id`	string	Target playlist ID
`songs`	array	Array of `{ song_title, song_url, artist }`

`list_playlists`

List all saved playlists.

`export_playlist`

Parameter	Type	Default	Description
`playlist_id`	string	required	Playlist to export
`format`	string	`json`	`json` or `csv`

🗺 Roadmap

These tools are planned for future releases. PRs welcome!

Tool	Description
`get_queue`	View the current playback queue
`add_to_queue`	Add a song to the queue without interrupting playback
`clear_queue`	Clear the current queue
`get_lyrics`	Fetch lyrics for the current or any song
`get_recommendations`	Get AI-recommended songs based on listening history
`get_artist_info`	Get artist bio, top songs, and discography
`get_album`	Browse an album and list all tracks
`get_trending`	Get trending songs and charts by region
`remove_from_history`	Delete a specific song from your history
`download_playlist`	Download an entire playlist at once
`set_sleep_timer`	Auto-pause playback after N minutes
`smart_playlist`	Auto-generate a playlist based on mood, genre, or history

📁 Project Structure

ytm-mcp/
├── src/
│   ├── index.ts          # MCP server entry point & tool handlers
│   ├── db.ts             # SQLite database setup & migrations
│   ├── browser/          # Playwright browser control
│   ├── history/          # YouTube Music history scraper
│   ├── downloader/       # yt-dlp search & download
│   ├── tools/            # Playback controls
│   ├── playlist/         # Playlist CRUD
│   └── api/              # YouTube Data API (optional)
├── downloads/            # Downloaded songs (gitignored)
├── db/                   # SQLite database (gitignored)
├── dist/                 # Compiled JS output
├── .env.example          # Environment variable template
└── README.md

❓ Troubleshooting

History returns empty
→ Make sure BROWSER_PROFILE points to a profile that's already logged into YouTube Music. Open it in Chrome/Chromium and sign in manually first.

Download fails with mutagen error

pip install mutagen --break-system-packages

Playback controls don't work
→ YouTube Music must be open in the browser. Run play_song first to open it.

chromium not found
→ Install it: sudo apt install chromium or adjust BROWSER_PROFILE to point to Chrome.

Build errors

rm -rf dist node_modules
npm install
npm run build

🤝 Contributing

Fork the repo
Create a feature branch: git checkout -b feat/my-tool
Commit your changes: git commit -m 'feat: add get_queue tool'
Push and open a PR

See the Roadmap for ideas on what to build next.

📄 License

MIT © 4shil

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
src		src
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

🎵 ytm-mcp

What is ytm-mcp?

✨ Features

🛠 Requirements

🚀 Installation

Find your Chrome profile path

.env Configuration

🔌 Connect to Your AI Tool

mcporter CLI

Claude Desktop

OpenClaw

Cursor

Antigravity

VS Code (GitHub Copilot)

Zed

Continue.dev

Any MCP Tool (Generic)

🧰 Tools Reference

🎧 History

get_history

🔍 Search & Download

search_song

download_song

download_history

list_downloads

▶️ Playback

play_song

playback_control

get_current_song

📋 Playlists

create_playlist

add_to_playlist

list_playlists

export_playlist

🗺 Roadmap

📁 Project Structure

❓ Troubleshooting

🤝 Contributing

📄 License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`.env` Configuration

`get_history`

`search_song`

`download_song`

`download_history`

`list_downloads`

`play_song`

`playback_control`

`get_current_song`

`create_playlist`

`add_to_playlist`

`list_playlists`

`export_playlist`

Packages