AI导哈

Spotify集成服务

一个提供Spotify音乐流媒体服务集成的MCP服务器，允许AI助手和应用程序与Spotify交互。

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

使用说明

Spotify MCP服务器

提供Spotify集成的模型上下文协议（MCP）服务器，允许AI助手和应用程序与Spotify的音乐流媒体服务进行交互。

特性

艺术家工具

  • 搜索艺术家 -按名称搜索艺术家
  • 获取艺术家 -获取特定艺术家的详细信息
  • 获取艺术家专辑 -获取艺术家的所有相册
  • 获取艺术家热门曲目 -获取艺术家最受欢迎的曲目

相册工具

  • 获取相册 -获取特定相册的详细信息
  • 获取专辑曲目 -从专辑中获取所有曲目
  • 获取新版本 -获取新专辑发布

播放列表工具

  • 创建播放列表 -创建新播放列表
  • 将曲目添加到播放列表 -将曲目添加到现有播放列表
  • 获取用户播放列表 -获取当前用户的播放列表

用户工具

  • 获取用户顶级艺术家 -获取用户最受关注的艺术家
  • 获取用户热门曲目 -获取用户收听次数最多的曲目

安装

适用于Claude桌面用户（推荐）

将此服务器与Claude Desktop一起使用的最简单方法是通过PyPI：

  1. 获取您的Spotify API证书（请参阅 Spotify API设置 在......下面
  2. 添加到您的Claude桌面配置 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）：
{
  "mcpServers": {
    "Spotify": {
      "command": "uvx",
      "args": ["spotify-mcp-server"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback"
      }
    }
  }
}
  1. 重新启动克劳德桌面
  2. 首次使用时，在提示时向Spotify进行身份验证

开发环境设置

先决条件

  • Python 3.10+
  • Spotify开发者帐户
  • MCP客户端（如克劳德桌面、光标等）

设置

1.安装依赖项

# Using uv (recommended)
uv sync

# Or using pip
pip install -r requirements.txt

2.Spotify API设置｛#Spotify-API-Setup｝

  1. 首选 Spotify开发者仪表板
  2. 创建新应用程序
  3. 添加 http://localhost:8888/callback 到应用程序的重定向URI
  4. 复制您的客户端ID和客户端密码

3.环境配置

创建一个 .env 项目根目录中的文件：

SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://localhost:8888/callback

4.身份验证

首次运行时，服务器将打开一个浏览器窗口进行Spotify身份验证。按照OAuth流程授权应用程序。

用法

运行服务器

# Development mode with inspector
mcp dev spotify_mcp_server.py

# Or run directly
python spotify_mcp_server.py

可用工具

艺人经纪

# Search for artists
search_artists(query="The Beatles", limit=10)

# Get artist details
get_artist(artist_id="3WrFJ7ztbogyGnTHbHJFl2")

# Get artist albums
get_artist_albums(artist_id="3WrFJ7ztbogyGnTHbHJFl2", include_groups="album,single")

# Get artist top tracks
get_artist_top_tracks(artist_id="3WrFJ7ztbogyGnTHbHJFl2", market="US")

相册管理

# Get album details
get_album(album_id="4aawyAB9vmqN3uQ7FjRGTy", market="US")

# Get album tracks
get_album_tracks(album_id="4aawyAB9vmqN3uQ7FjRGTy", limit=20)

# Get new releases
get_new_releases(country="US", limit=20)

播放列表管理

# Create a new playlist
create_playlist(name="My New Playlist", description="A great playlist", public=False)

# Add tracks to playlist
add_tracks_to_playlist(playlist_id="playlist_id", track_uris=["spotify:track:track_id"])

# Get user playlists
get_user_playlists()

用户数据

# Get user's top artists
get_user_top_artists(time_range="medium_term", limit=20)

# Get user's top tracks
get_user_top_tracks(time_range="short_term", limit=10)

项目结构

spotify-mcp/
├── spotify_mcp_server.py    # Main MCP server
├── mcp_tools/              # Tool modules
│   ├── __init__.py
│   ├── artist_tools.py     # Artist-related tools
│   ├── playlist_tools.py   # Playlist-related tools
│   ├── albums.py          # Album-related tools
│   └── user_tools.py      # User-related tools
├── .env                    # Environment variables
├── .spotify_cache         # Spotify OAuth cache
├── requirements.txt        # Python dependencies
└── README.md             # This file

API 参考

艺术家工具

search_artists

在Spotify上搜索艺术家。

参数：

  • query （str）：搜索艺术家姓名
  • limit （int，可选）：最大结果数（默认值：10，最大值：50）

退货：

  • 艺术家列表，包括ID、姓名、受欢迎程度、关注者、流派和Spotify URL

get_artist

获取艺术家的详细信息。

参数：

  • artist_id （str）：Spotify艺术家ID

退货：

  • 详细的艺术家信息，包括图像、流派和受欢迎程度

get_artist_albums

为艺术家获取专辑。

参数：

  • artist_id （str）：Spotify艺术家ID
  • include_groups （str，可选）：要包含的专辑类型（默认：“专辑，单曲”）
  • limit （int，可选）：要返回的最大相册数（默认值：20，最大值：50）

退货：

  • 专辑列表，包括发行日期、曲目数和封面图片等详细信息

get_artist_top_tracks

获得艺术家的顶级曲目。

参数：

  • artist_id （str）：Spotify艺术家ID
  • market （str，可选）：市场/国家代码（默认：“US”）

退货：

  • 热门曲目列表，包括流行度、持续时间和专辑信息

相册工具

get_album

获取有关相册的详细信息。

参数：

  • album_id （str）：Spotify专辑ID
  • market （str，可选）：市场/国家代码（默认：“US”）

退货：

  • 详细的专辑信息，包括艺术家、图像和流派

get_album_tracks

从专辑中获取曲目。

参数：

  • album_id （str）：Spotify专辑ID
  • market （str，可选）：市场/国家代码（默认：“US”）
  • limit （int，可选）：要返回的最大曲目数（默认值：20，最大值：50）
  • offset （int，可选）：起始索引（默认值：0）

退货：

  • 包含曲目编号、持续时间和艺术家信息的曲目列表

get_new_releases

获取新专辑发行。

参数：

  • country （str，可选）：国家代码（默认：“US”）
  • limit （int，可选）：要返回的最大相册数（默认值：20，最大值：50）
  • offset （int，可选）：起始索引（默认值：0）

退货：

  • 包含艺术家和图像信息的新发行专辑列表

播放列表工具

create_playlist

创建新的Spotify播放列表。

参数：

  • name （str）：播放列表的名称
  • description （str，可选）：播放列表的描述
  • public （bool，可选）：播放列表是否公开（默认值：False）
  • collaborative （bool，可选）：播放列表是否协作（默认值：False）

退货：

  • 播放列表信息，包括ID、名称和Spotify URL

add_tracks_to_playlist

将曲目添加到现有播放列表中。

参数：

  • playlist_id （str）：Spotify播放列表ID
  • track_uris （List[str]）：Spotify曲目URI列表

退货：

  • 成功状态和添加的曲目数量

get_user_playlists

获取当前用户的播放列表。

参数：

  • 无

退货：

  • 用户播放列表列表，包括曲目计数和隐私设置等详细信息

用户工具

get_user_top_artists

从Spotify获取用户收听次数最多的艺术家。

参数：

  • time_range （str，可选）：顶级艺术家的时间段（默认值：“medium_term”）
    • "short_term"：过去4周
    • "medium_term"：过去6个月
    • "long_term"：几年
  • limit （int，可选）：要返回的艺术家的最大数量（默认值：20，最大值：50）
  • offset （int，可选）：返回的第一位艺术家的索引（默认值：0）

退货：

  • 包含ID、姓名、受欢迎程度、关注者、流派和Spotify URL的顶级艺术家列表

get_user_top_tracks

从Spotify获取用户收听次数最多的曲目。

参数：

  • time_range （str，可选）：首曲目的时间段（默认值：“medium_term”）
    • "short_term"：过去4周
    • "medium_term"：过去6个月
    • "long_term"：几年
  • limit （int，可选）：要返回的最大曲目数（默认值：20，最大值：50）
  • offset （int，可选）：要返回的第一个轨道的索引（默认值：0）

退货：

  • 包含ID、名称、专辑信息、艺术家、流行度、持续时间和Spotify URL的热门曲目列表

发展

添加新工具

  1. 在相应的工具模块中创建新功能(artist_tools.py, playlist_tools.py, albums.py，或 user_tools.py)
  2. 将该功能添加到 __init__.py 出口
  3. 在中创建包装器函数 spotify_mcp_server.py
  4. 复制文档字符串并注册该工具

测试

# Run the server in development mode
mcp dev spotify_mcp_server.py

# The MCP Inspector will open at http://localhost:6274
# Use it to test your tools interactively

故障排除

身份验证问题

  • 确保您的 .env 文件具有正确的Spotify凭据
  • 检查您的重定向URI是否完全匹配： http://localhost:8888/callback
  • 清除 .spotify_cache 如果遇到令牌问题，请提交文件

API费率限制

  • Spotify对API呼叫有费率限制
  • 服务器包括对速率限制响应的错误处理
  • 考虑对频繁访问的数据实施缓存

相关 MCP