<div align="center">

🎵 SpotiMCP

</div>

使用模型上下文协议（MCP）实现的AI驱动的Spotify集成

连接Claude桌面与Spotify Web API的MCP服务器

🎯 功能概述

该项目在Claude桌面与Spotify之间建立了一个桥梁，允许您通过自然语言命令控制您的音乐。

特性

• 搜索 轨道、专辑、艺术家和播放列表
• 获取信息 关于音乐项目的详细信息
• 控制播放 （播放、暂停、跳过） - 需要Spotify Premium
• 管理播放列表 （创建、添加/移除轨道、修改详情）
• 队列管理 - 需要Spotify Premium

🚀 快速开始

先决条件

• Python 3.12+
• UV 包管理器
• Spotify Premium账户（用于播放功能）
• Claude桌面

设置步骤

1. 从Spotify开发者仪表板获取API凭证：Spotify开发者仪表板

   • 创建一个应用，重定向URI设置为：http://127.0.0.1:8080/callback

2. 安装依赖项

   uv sync
   

3. 设置环境变量

   export SPOTIFY_CLIENT_ID="your_client_id"
   export SPOTIFY_CLIENT_SECRET="your_client_secret"
   export SPOTIFY_REDIRECT_URI="http://127.0.0.1:8080/callback"
   

4. 运行MCP服务器

   uv run spotify-mcp
   

5. 配置Claude桌面

   在您的Claude桌面配置中添加：

   {
     "mcpServers": {
       "spotify": {
         "command": "uv",
         "args": [
           "--directory",
           "/path/to/spotify-mcp",
           "run",
           "spotify-mcp"
         ],
         "env": {
           "SPOTIFY_CLIENT_ID": "YOUR_CLIENT_ID",
           "SPOTIFY_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
           "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8080/callback"
         }
       }
     }
   }
   

💬 使用示例

一旦配置完成，您可以在Claude桌面中使用自然语言命令：

"搜索The Beatles的歌曲"
"播放'Here Comes the Sun'"
"创建一个名为'My Favorites'的播放列表"
"显示我的播放列表"
"将这首歌添加到我的队列中"

🛠 技术细节

架构

Claude桌面 → MCP协议 → Python服务器 → Spotify Web API

主要组件

• server.py - 包含工具定义的MCP服务器
• spotify_api.py - 处理OAuth的Spotify API客户端
• utils.py - 数据解析和验证工具

可用工具

• 搜索 - 查找轨道、专辑、艺术家、播放列表
• 获取信息 - 获取音乐项目的详细信息
• 播放控制 - 控制音乐播放（需Premium）
• 队列管理 - 管理播放队列（需Premium）
• 播放列表 - 创建和管理播放列表

🔧 开发

项目结构

src/spotify_mcp/
├── __init__.py      # 包入口点
├── server.py        # MCP服务器实现
├── spotify_api.py   # Spotify API客户端
└── utils.py         # 工具函数

依赖项

• mcp==1.3.0 - 模型上下文协议
• spotipy==2.24.0 - Spotify Web API客户端
• python-dotenv>=1.0.1 - 加载环境变量

🐛 故障排除

常见问题

认证失败：

• 检查您的Spotify应用重定向URI是否完全匹配
• 确保环境变量设置正确
• 尝试重启Claude桌面

没有活动设备：

• 确保Spotify已打开并正在播放
• 检查您是否有Spotify Premium（播放所需）

MCP连接问题：

• 验证服务器是否正在运行：uv run spotify-mcp
• 检查Claude桌面日志中的连接错误

调试模式

使用MCP Inspector进行调试：

npx @modelcontextprotocol/inspector uv --directory . run spotify-mcp

---

简单、干净的AI与音乐控制集成