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原语覆盖：

🛠️ 工具

📦 资源（Claude被动可读）

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

______________________________________________________________________

安装

先决条件

• 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

1. 添加配置：

{
  "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里希·拉吉·森

______________________________________________________________________

链接

• 讨论

______________________________________________________________________

⭐ 星如果有用！