ytm MCP

🎵 ytm-mcp

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

______________________________________________________________________

什么是ytm-mcp？

ytm-mcp 是一个 模型上下文协议（MCP） 服务器，让AI助手完全控制YouTube音乐。将其连接到Claude、Cursor、VS Code或任何兼容MCP的工具，并用自然语言控制您的音乐。

"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"

______________________________________________________________________

✨ 特性

______________________________________________________________________

🛠 需求

• Node.js 18+
• yt-dlp --用于下载歌曲
• Python诱变剂 --用于嵌入元数据： pip install mutagen
• 铬或铬 --必须登录YouTube音乐

______________________________________________________________________

🚀 安装

# 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

查找您的Chrome个人资料路径

这是浏览器存储登录会话的文件夹。

⚠️ 该个人资料必须已登录到YouTube音乐。服务器不会处理登录，只需重用现有会话即可。

.env 配置

# 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

______________________________________________________________________

🔌 连接到您的AI工具

mcporter命令行界面

安装 麦波特 并注册ytm-mcp：

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

列出所有工具：

mcporter list ytm-mcp

直接从终端调用工具：

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_config.json:

• Linux： ~/.config/Claude/claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %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"
      }
    }
  }
}

重新启动克劳德桌面。您将在工具列表中看到ytm-mcp。 ✅

______________________________________________________________________

开爪

添加 ~/.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"
        }
      }
    ]
  }
}

或者与mcporter合作：

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

______________________________________________________________________

光标

创建或编辑 ~/.cursor/mcp.json:

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

______________________________________________________________________

反重力

创建 mcp.json 在Antigravity用户配置目录中：

• Linux： ~/.config/Antigravity/User/mcp.json
• macOS： ~/Library/Application Support/Antigravity/User/mcp.json
• 窗户： %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"
      }
    }
  }
}

重新加载反重力(Ctrl+Shift+P → Developer: Reload Window). ✅

______________________________________________________________________

VS代码（GitHub副本）

创建 .vscode/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"
      }
    }
  }
}

______________________________________________________________________

泽德

添加 ~/.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

添加 ~/.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"
          }
        }
      }
    ]
  }
}

______________________________________________________________________

任何MCP工具（通用）

ytm-mcp使用标准 stdio传输任何MCP兼容工具都可以连接：

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

______________________________________________________________________

🧰 工具参考

🎧 历史

get_history

删除您的YouTube音乐收听历史记录。

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

______________________________________________________________________

🔍 搜索与下载

search_song

在YouTube音乐中搜索歌曲。

download_song

通过URL下载一首歌曲。

download_history

批量下载您最近的收听历史记录。

list_downloads

列出所有下载的文件及其大小和时间戳。

______________________________________________________________________

▶️ 回放

play_song

搜索并播放歌曲，或通过直接URL播放。

playback_control

在一个工具中实现完全播放控制。

get_current_song

获取当前播放状态。

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

______________________________________________________________________

📋 播放列表

create_playlist

add_to_playlist

list_playlists

列出所有已保存的播放列表。

export_playlist

______________________________________________________________________

🗺 路线图

这些工具计划在未来发布。PR欢迎！

______________________________________________________________________

📁 项目结构

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

______________________________________________________________________

❓ 故障排除

历史记录返回为空\ → 确保 BROWSER_PROFILE 指向已登录YouTube音乐的个人资料。在Chrome/Chromium中打开它，然后先手动登录。

下载失败，出现诱变剂错误

pip install mutagen --break-system-packages

播放控制不起作用\ → YouTube音乐必须在浏览器中打开。跑 play_song 首先打开它。

chromium 未找到\ → 安装它： sudo apt install chromium 或调整 BROWSER_PROFILE 指向Chrome。

构建错误

rm -rf dist node_modules
npm install
npm run build

______________________________________________________________________

🤝 贡献

1. 分叉回购
2. 创建要素分支： git checkout -b feat/my-tool
3. 提交您的更改： git commit -m 'feat: add get_queue tool'
4. 推送并打开PR

看 路线图 关于接下来要构建什么的想法。

______________________________________________________________________

📄 许可证

MIT© 4小时