ytm-mcp

ytm-mcp

A full-featured YouTube Music MCP server that lets AI assistants control playback, browse history, download songs, and manage playlists via natural language.

Category
访问服务器

README

<p align="center"> <h1 align="center">🎵 ytm-mcp</h1> <p align="center">A full-featured <strong>YouTube Music MCP server</strong> — control playback, browse history, download songs, manage playlists, and more from any AI assistant.</p> <p align="center"> <a href="https://github.com/4shil/ytm-mcp/stargazers"><img src="https://img.shields.io/github/stars/4shil/ytm-mcp?style=flat-square" /></a> <a href="https://github.com/4shil/ytm-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" /></a> <img src="https://img.shields.io/badge/MCP-compatible-brightgreen?style=flat-square" /> <img src="https://img.shields.io/badge/built%20with-TypeScript-blue?style=flat-square" /> </p> </p>

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

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

See the Roadmap for ideas on what to build next.

📄 License

MIT © 4shil

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选