使用说明
🎵 Spotify MCP-模型上下文协议实现
只需一个提示即可创建整个Spotify播放列表，或使用AI按音乐类型拆分大型播放列表。
📖 关于项目
Spotify MCP 是一个实用的实现 模型上下文协议（MCP） 它展示了人工智能助手如何以标准化的方式与外部服务进行交互。该项目以Spotify为例，展示了MCP的功能。
什么是模型上下文协议？
模型上下文协议是一个开放标准，使人工智能模型能够安全地连接到外部数据源和工具。MCP为AI模型提供了一种与任何服务交互的通用方式，而不是具有硬编码集成的AI模型。
┌─────────────────┐
│ AI Model │
│ (Gemini) │
└────────┬────────┘
│
│ MCP Protocol
│
┌────────▼────────┐
│ MCP Server │◄──── Standardized Interface
│ (Spotify) │
└────────┬────────┘
│
│ REST API
│
┌────────▼────────┐
│ Spotify API │
└─────────────────┘
为什么这个项目很重要：
- 🎓 教育的：通过构建实用的东西来学习MCP
- 🔌 可重复使用的：服务器架构可以适用于其他API
- 🚀 生产准备就绪：基于Docker的TypeScript和Python部署
- 💡 真实世界用例：解决Spotify播放列表管理的实际挑战
✨ 特性
🎼 创建播放列表
- 自然语言播放列表：从单个提示生成整个播放列表
- “创建包含20首高能量歌曲的锻炼播放列表”
- “为我制作一个用于学习的冷爵士播放列表”
🎯 智能轨迹搜索
- 使用会话语言搜索Spotify的目录
- 获取曲目详细信息，包括URI、艺术家和专辑信息
📝 播放列表管理
- 创建公共或私人播放列表
- 在批量操作中添加多个轨道
- 完全控制播放列表元数据
🎨 基于类型的组织
- 即将推出：按音乐类型拆分大型播放列表
- 智能组织您的图书馆
🎬 演示
在几秒钟内创建播放列表
在一个提示中用自然语言创建的完整播放列表
🚀 快速开始
先决条件
在开始之前，请确保您已经：
Spotify设置
- 首选 Spotify开发者仪表板
- 点击 “创建应用程序”
- 填写应用程序详细信息：
- 应用程序名称：MCP Spotify（或任何名称）
- 应用描述：模型上下文协议实现
- 重定向URI:
http://localhost:8080
- 保存并复制您的 客户端ID 和 客户端密钥
安装
# 1. Clone the repository
git clone https://github.com/Gregoire-W/mcp-spotify.git
cd mcp-spotify
# 2. Configure MCP Server environment
cd mcp-server
echo "SPOTIFY_CLIENT_ID=your_client_id_here" > .env
echo "SPOTIFY_CLIENT_SECRET=your_client_secret_here" >> .env
cd ..
# 3. Configure MCP Client environment
cd mcp-client
echo "GOOGLE_GENAI_API_KEY=your_gemini_api_key_here" > .env
echo "SPOTIFY_CLIENT_ID=your_client_id_here" >> .env
cd ..
# 4. Launch with Docker Compose
docker compose up --build
# 5. Open your browser
# Navigate to: http://localhost:8080
首次运行
- 打开
http://localhost:8080在浏览器中 - Streamlit界面将加载
- 点击 “连接到Spotify” 侧边栏中的验证按钮
- 连接后，开始聊天！尝试： “创建一个名为“Road Trip”的播放列表，其中包含15首欢快的歌曲”
🏗️ 建筑
技术栈
| 组件 | 技术 | 目的 |
|---|---|---|
| MCP服务器 | TypeScript+Express | 实现MCP协议和Spotify集成 |
| MCP客户端 | Python | 处理MCP客户端通信 |
| AI模型 | Google Gemini 2.5 Flash | 自然语言处理和工具调用 |
| 用户界面 | Streamlit | 简单有效的聊天界面 |
| 部署 | Docker Compose | 容器化多服务架构 |
系统架构
┌──────────────────────────────────────────────────────────┐
│ User Interface │
│ Streamlit (Port 8080) │
└───────────────────────────┬──────────────────────────────┘
│
┌───────▼────────┐
│ MCP Client │
│ (Python) │
│ │
│ • Session │
│ • Gemini API │
└───────┬────────┘
│ MCP Protocol
│ (HTTP)
┌───────▼────────┐
│ MCP Server │
│ (TypeScript) │
│ │
│ Tools: │
│ • createPlaylist
│ • searchTracks
│ • addTrack │
└───────┬────────┘
│ OAuth 2.0
│ REST API
┌───────▼────────┐
│ Spotify API │
└────────────────┘
MCP工具实施
服务器通过MCP协议公开了三个主要工具：
1. createPlaylist
Input: {
playlistName: string
playlistDescription: string
isPublic: boolean
}
Output: {
success: boolean
playlistId: string
message: string
}
2. searchTracks
Input: {
query: string
}
Output: {
tracks: [{
uri: string
name: string
artists: string[]
album: string
}]
success: boolean
}
3. addTrackToPlaylist
Input: {
playlistId: string
uris: string[]
}
Output: {
success: boolean
message: string
}
🔧 配置
环境变量
MCP服务器(mcp-server/.env)
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
MCP客户端(mcp-client/.env)
GOOGLE_GENAI_API_KEY=your_gemini_api_key
SPOTIFY_CLIENT_ID=your_spotify_client_id
升级AI能力
该项目使用 双子座2.5闪光灯 默认情况下为（免费层）。为了获得更好的性能：
- 升级到 双子座2.5 Pro 在
mcp-client/client.py:
response = self.client.models.generate_content(
model="gemini-2.5-pro", # Changed from gemini-2.5-flash
contents=self.messages,
config=config,
)
- 其他兼容型号：
gemini-2.5-pro：质量最好，速度较慢gemini-2.5-flash：平衡（默认）gemini-2.0-flash-exp：最快，实验性
📚 文档
项目结构
mcp-spotify/
├── mcp-server/ # TypeScript MCP Server
│ ├── src/
│ │ ├── index.ts # Server entry point & tool registration
│ │ ├── clients/
│ │ │ └── spotifyApiClient.ts # Spotify API wrapper
│ │ └── types/
│ │ └── track.ts # TypeScript type definitions
│ ├── Dockerfile.prod
│ ├── package.json
│ └── tsconfig.json
│
├── mcp-client/ # Python MCP Client
│ ├── client.py # MCP client implementation
│ ├── streamlit_app.py # UI interface
│ ├── requirements.txt
│ └── Dockerfile.prod
│
└── docker-compose.yml # Multi-container orchestration
发展
本地运行（无Docker）
服务器：
cd mcp-server
npm install
npm run build
node build/index.js
客户：
cd mcp-client
pip install -r requirements.txt
streamlit run streamlit_app.py --server.port 8080
测试MCP服务器
使用MCP检查器测试您的服务器：
npx @modelcontextprotocol/inspector http://localhost:3000/mcp
🤝 贡献
贡献是开源社区令人惊叹的地方！你所做的任何贡献都是 非常感谢.
- 分叉项目
- 创建功能分支(
git checkout -b feature/AmazingFeature) - 提交您的更改(
git commit -m 'Add some AmazingFeature') - 推到分支机构(
git push origin feature/AmazingFeature) - 打开拉取请求
🐛 故障排除
常见问题
端口已在使用中
# Change ports in docker-compose.yml
ports:
- "8081:8080" # Use 8081 instead of 8080
Spotify身份验证失败
- 在中验证您的客户端ID和客户端密码
.env - 确保重定向URI设置为
http://localhost:8080在Spotify仪表板中 - 检查您在首次运行时是否已授权该应用程序
Docker构建失败
# Clean Docker cache and rebuild
docker compose down
docker system prune -a
docker compose up --build
📝 许可证
根据MIT许可证分发。看 LICENSE 了解更多信息。
🙏 致谢
- 模型上下文协议 -MCP规范和SDK
- Anthropic -用于创建和维护MCP
- Spotify Web API -音乐数据和控件
- 谷歌双子座 -具有函数调用的AI模型
- 溪流 -快速UI原型制作
📧 联系
格雷瓜尔·W- @格雷瓜尔-W
项目链接： https://github.com/Gregoire-W/mcp-spotify
⭐ 如果你觉得这个repo有用，请将其标记为星号！
由...制作❤️ 还有很多☕
