AI导哈

YouTube音乐MCP服务器

一个生产级的模型上下文协议（MCP）服务器，连接YouTube Music和Claude等AI助手，实现完整的MCP原语集（工具、资源和提示），提供真正的代理音乐体验。

  • by codeRisshi25
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 codeRisshi25/youtubemusic-mcp

使用说明

YouTube音乐MCP服务器

一个生产级的模型上下文协议（MCP）服务器，将YouTube音乐连接到克劳德等人工智能助手。
实现完整的MCP基元集-- 工具、资源和提示 --真正的主体音乐体验。

建筑 • 特性 • 安装 • 认证 • 用法 • 工具 • 资源 • 提示

建筑

┌────────────────────────────────────────────────────────────┐
│                    Claude / AI Assistant                   │
└──────────────────────┬─────────────────────────────────────┘
                       │  Model Context Protocol (stdio)
┌──────────────────────▼─────────────────────────────────────┐
│                 YouTube Music MCP Server v2                │
│                                                            │
│  ┌─────────────┐  ┌───────────────┐  ┌──────────────────┐  │
│  │  15 Tools   │  │  3 Resources  │  │    3 Prompts     │  │
│  │             │  │               │  │                  │  │
│  │ search      │  │library://     │  │weekly-discovery  │  │
│  │ stats       │  │  songs        │  │mood-based-       │  │
│  │ similar ★   │  │  artists      │  │  playlist        │  │
│  │ recommend ★ │  │  playlists    │  │artist-deep-dive  │  │
│  │ smart pl ★  │  └───────────────┘  └──────────────────┘  │
│  │ charts      │                                           │
│  │ insights    │  ┌───────────────────────────────────┐    │
│  │ moods       │  │  TTL Cache (5 min)  •  Async ★    │    │
│  │ ...         │  │  Custom Exceptions  •  Logging    │    │
│  └─────────────┘  └───────────────────────────────────┘    │
└──────────────────────┬─────────────────────────────────────┘
                       │  ytmusicapi
┌──────────────────────▼─────────────────────────────────────┐
│                   YouTube Music API                        │
└────────────────────────────────────────────────────────────┘
★ = Agentic / async feature

特性

15个工具·3个资源·3个提示——完整的MCP原语覆盖：

🛠️ 工具

工具 说明
get_liked_songs_count 歌曲总数（绕过YT显示限制）
get_library_stats 歌曲、艺术家、播放列表+详细分类
search_music 使用类型过滤器搜索（歌曲/专辑/艺术家/播放列表/视频）
get_top_artists 用视觉进度条对艺术家进行排名
find_similar_songs ⭐ 真实 YTMusic广播引擎——不是虚假的艺术家搜索
get_recommendations ⭐ 前5位艺术家的异步并行获取
create_playlist_from_songs 根据搜索查询创建和填充播放列表
list_playlists 所有带有ID和歌曲计数的播放列表
get_playlist_songs 浏览任何播放列表中的歌曲
add_songs_to_playlist 将歌曲添加到现有播放列表
build_smart_playlist ⭐ 能动性 6步流程：情绪→类别→曲目→过滤器→保存
explore_moods 发现所有YTMusic情绪和流派类别
get_charts 全球或特定国家的趋势图
get_listening_insights 历史分析：模式、多样性得分、见解
get_server_info 身份验证方法、缓存状态、版本、功能

📦 资源（Claude被动可读）

资源URI 描述
library://songs 结构化JSON格式的完整库
library://artists 艺术家百分比排名
library://playlists 所有播放列表均为结构化JSON

💬 提示（引导对话开始者）

提示 描述
weekly-discovery-mix 指导每周音乐发现工作流程
mood-based-playlist 协作情绪→ 播放列表会话
artist-deep-dive 完整的艺术家探索+聆听计划

安装

先决条件

  • Python 3.10或更高版本
  • YouTube音乐帐户
  • 浏览器开发工具访问（用于身份验证）

设置

  1. 克隆存储库
git clone https://github.com/codeRisshi25/youtubemusic-mcp.git
cd youtubemusic-mcp
  1. 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# OR
venv\Scripts\activate     # Windows
  1. 安装依赖项
pip install -e .

认证

选择一种身份验证方法：

选项A：Cookie文件（最简单——推荐）

  1. 访问 music.youtube.com 并登录
  2. 打开开发人员工具(F12)
  3. 首选 网络 选项卡并刷新页面
  4. 点击任何请求→ 标头 → 复制完整 cookie: 价值
  5. 将其粘贴到名为的文件中 cookie.txt 在项目目录中
  6. 完成！ 服务器自动生成 browser.json 首次启动时
# Optional: validate cookies before starting the server
python update_auth.py

注： Cookie通常持续6-24个月。当它们过期时，只需将新鲜的饼干粘贴到 cookie.txt 并重新启动。

选项B:OAuth（长期）

看 docs/OAUTH_SETUP.md 获取完整的OAuth设置说明。

用法

使用MCP检查员进行测试

npx @modelcontextprotocol/inspector venv/bin/python server.py

打开web界面 http://localhost:6274 测试所有15个工具、3个资源和3个提示。

Claude桌面集成

  1. 配置文件位置：

    • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
    • 窗户： %APPDATA%\Claude\claude_desktop_config.json
    • Linux： ~/.config/Claude/claude_desktop_config.json

  2. 添加配置：

{
  "mcpServers": {
    "youtube-music": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/server.py"]
    }
  }
}
  1. 重新启动克劳德桌面

看 docs/CLAUDE_SETUP.md 详细说明。

可用工具

看 功能部分 上面是所有15种工具的完整表格。

机构亮点

build_smart_playlist --核心代理工具。在单个工具调用中运行一个6步流水线：

Step 1: Fetch all Moods & Genres from YouTube Music
Step 2: Match your mood keyword to a real category
Step 3: Pull mood playlist pool from that category
Step 4: Sample tracks across multiple playlists
Step 5: Apply energy-level filter (high/medium/low)
Step 6: Optionally create & save to YouTube Music

find_similar_songs --用途 get_watch_playlist(radio=True)，真正的YTMusic相似性引擎，而不是虚假的艺术家搜索。

get_recommendations --从5位艺术家那里获取 asyncio.gather() 真正的并行执行。

运行测试

pip install -e ".[dev]"
pytest tests/ -v

51个测试，涵盖身份验证、缓存、所有工具、资源、提示和路由——不需要网络（完全模拟）。

故障排除

身份验证错误

如果您在大约6个月后出现身份验证错误：

  1. 您的Cookie可能已过期
  2. 按照中的简单更新过程进行操作 docs/AUTH_UPDATE.md
  3. 您只需从浏览器中粘贴新的Cookie

在Claude中未检测到服务器

  • 在中使用绝对路径 claude_desktop_config.json
  • 配置更改后重新启动Claude Desktop
  • 检查克劳德的日志→ Help → 查看日志

导入错误

  • 确保虚拟环境已激活
  • 跑 pip install -e . 在项目目录中

启动时服务器崩溃

  • 验证 browser.json 或 oauth.json 存在
  • 检查文件权限
  • 看 docs/CLAUDE_SETUP.md 详细故障排除

贡献

看 docs/CONTRIBUTING.md 关于贡献指南。

许可证

MIT许可证-请参阅 许可证

版权所有（c）2025里希·拉吉·森

链接

建于 ytmusicapi • 主控程序

⭐ 星如果有用！

相关 MCP