# Spotify MCP Server

基于Spotify OAuth和MCP协议的Python服务器，提供Spotify音乐控制功能。

## 功能特性

- ✅ Spotify OAuth认证
- ✅ 获取当前播放状态
- ✅ 播放/暂停控制
- ✅ 上一首/下一首切换
- ✅ 音量控制
- ✅ 播放位置跳转
- ✅ 设备管理

## 安装

1. 安装依赖：
```bash
pip install -e .
```

2. 配置Spotify OAuth凭据：
   - 访问 [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
   - 创建应用并获取 `Client ID` 和 `Client Secret`
   - 设置重定向URI为 `http://127.0.0.1:8000/callback`

3. 设置环境变量：
```bash
export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"
export SPOTIFY_REDIRECT_URI="http://127.0.0.1:8000/callback"  # 可选，默认值
```

## 使用方法

### 1. 启动MCP服务器

服务器通过stdio通信，通常由MCP客户端（如Claude Desktop）自动启动。

### 2. 首次认证

1. 调用 `spotify_get_auth_url` 工具获取授权URL
2. 在浏览器中访问该URL并完成授权
3. 从回调URL中提取授权码（`code`参数）
4. 调用 `spotify_authenticate` 工具，传入授权码完成认证

认证信息会保存在 `~/.spotify_mcp_token.json`，后续使用会自动刷新token。

### 3. 使用控制功能

认证成功后，可以使用以下工具：

- `spotify_get_current_playback` - 获取当前播放状态
- `spotify_pause` - 暂停播放
- `spotify_next` - 下一首
- `spotify_previous` - 上一首
- `spotify_set_volume` - 设置音量（0-100）
- `spotify_seek` - 跳转到指定位置
- `spotify_get_devices` - 获取可用设备列表
- `spotify_play_artist` - 搜索并播放指定艺术家的top 10 tracks，如 'Taylor Swift的歌曲'
- `spotify_play_song` - 根据歌手和歌曲名播放歌曲。例如：播放 Taylor Swift 的 Love Story

## MCP客户端配置

在Claude Desktop的配置文件中添加：

```json 
{
  "mcpServers": {
    "spotify-mcp": {
      "command": "python",
      "args": ["-m", "spotify_mcp"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI"="http://127.0.0.1:8000/callback"
      }
    }
  }
}
```
或者使用uv
```json
{
  "mcpServers": {
    "spotify-mcp": {
      "command": "uv",
      "args": ["run", "-m", "spotify_mcp"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI"="http://127.0.0.1:8000/callback"

      }
    }
  }
}
```




## 注意事项

- 确保Spotify应用已开启并正在播放音乐
- 某些功能需要Spotify Premium账户
- Token会自动刷新，无需手动重新认证
- 设备ID参数为可选，不指定时使用当前活动设备

## 许可证

MIT