Airsonic MCP

声波MCP🎵

一个完整的MCP（模型上下文协议）服务器，与Airsonic音乐服务器集成，允许LLM通过自然语言控制音乐播放。

特性

• ✅ 完整的MCP协议 -兼容JSON-RPC 2.0，可与Groq和其他MCP客户端配合使用
• ✅ 真正的Airsonic集成 -对Airsonic服务器的实际API调用（无模拟）
• ✅ 网络音频播放器 -HTML5播放器可通过浏览器访问
• ✅ LLM控制 -通过自然语言搜索、播放、暂停和控制音乐
• ✅ 生产就绪 -干净、模块化的架构

快速开始

1.配置Airsonic服务器

编辑 config.json 使用您的Airsonic服务器详细信息：

{
  "airsonic": {
    "server_url": "http://localhost:4040",
    "username": "your_username",
    "password": "your_password",
    "api_version": "1.16.0"
  }
}

2.安装依赖项

pip install -r requirements.txt

3.启动MCP服务器

uvicorn main:app --reload

✅ 服务器正在运行 http://localhost:8000

4.访问Web播放器

打开浏览器并转到：

http://localhost:8000/player

5.连接到Groq（可选）

1. 使用Cloudflare Tunnel暴露您的服务器：

   cloudflared tunnel --url http://localhost:8000

1. 在Groq控制台中添加MCP服务器：

- 服务器URL: https://your-cloudflare-url.trycloudflare.com - 问：“搜索披头士乐队的歌曲”或“播放我最喜欢的播放列表”

可用的MCP工具

LLM可以使用这些工具来控制音乐：

• search_songs（查询） -在曲库中搜索歌曲
• play_song（song_id） -播放特定歌曲
• pause_playback（） -暂停当前播放
• resume_playback（） -恢复暂停的播放
• stop_playback（） -停止当前播放
• get_current_song（） -获取当前播放的歌曲信息
• get_playlists（） -列出所有播放列表
• play_playlist（playlist_id） -播放播放列表

建筑

LLM (Groq) → MCP Server → Airsonic API → Music Library
                    ↓
              Web Player (Browser)

API终点

• GET / -服务器信息
• POST /initialize -MCP初始化
• POST /tools/list -列出可用工具
• POST /tools/call -执行工具
• GET /player -网络音频播放器界面
• GET /stream/{song_id} -从Airsonic流式传输音频
• GET /api/playback/state -获取当前播放状态
• POST /api/playback/control -控制播放（暂停/恢复/停止）

需求

• Python 3.9+
• Airsonic服务器正在运行且可访问
• FastAPI、uvicorn、requests、pydantic

故障排除

Airsonic连接问题

• 验证 config.json 具有正确的服务器URL和凭据
• 直接测试API气声： curl "http://your-server:4040/rest/ping.view?u=user&p=pass&v=1.16.0&c=mcp"
• 检查Airsonic服务器日志中的身份验证错误

播放不起作用

• 确保Airsonic服务器可从MCP服务器访问
• 检查歌曲ID是否有效（使用search_songs查找ID）
• 验证流端点是否可访问： http://localhost:8000/stream/{song_id}

Web播放器问题

• 打开浏览器控制台查看错误消息
• 检查 /api/playback/state 端点返回有效的JSON
• 如果远程访问，请确保音频播放器具有正确的CORS标头

示例用法

通过LLM（Groq）

User: "Search for songs by Pink Floyd"
LLM: [calls search_songs("Pink Floyd")]
Response: "Found 15 songs: 1. Comfortably Numb (ID: 1234)..."

User: "Play Comfortably Numb"
LLM: [calls play_song("1234")]
Response: "Now playing: Comfortably Numb by Pink Floyd..."

通过网络播放器

1. 打开 http://localhost:8000/player
2. 搜索歌曲
3. 使用播放/暂停/停止控制
4. 当LLM更改播放时，播放器会自动更新

许可证

开源-随意使用和修改！

______________________________________________________________________

准备好用AI控制音乐了吗？ 按照上面的快速开始！ 🎶