Metadata-Version: 2.4
Name: xiaozhi-music-mcp
Version: 1.0.0
Summary: 小智AI免费音乐MCP服务器 (STDIO版，可托管部署到 ModelScope 魔搭)
License: MIT
Keywords: mcp,music,xiaozhi,modelscope
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# xiaozhi-music-mcp

小智AI免费音乐 MCP 服务器（STDIO 传输，标准 MCP 2024-11-05 协议）。

提供音乐搜索、播放控制、音量调节、播放列表管理等工具，供小智 AI / 其他 MCP 客户端调用。

## 功能

| 工具 | 说明 |
|---|---|
| search_music | 搜索音乐（歌曲名/歌手/专辑） |
| play_music / pause_music / resume_music / stop_music | 播放控制 |
| set_volume | 音量 0-100 |
| add_to_playlist / get_playlist / clear_playlist | 播放列表管理 |
| next_song / previous_song | 切歌 |

## 本地运行

```bash
pip install xiaozhi-music-mcp
xiaozhi-music-mcp
```

## 魔搭 ModelScope 托管部署配置

在魔搭 MCP 创建/设置页填写服务配置（STDIO 类型）：

```json
{
  "mcpServers": {
    "xiaozhi-music-mcp": {
      "command": "uvx",
      "args": ["xiaozhi-music-mcp"]
    }
  }
}
```

托管类型选择“可托管部署”。部署检测通过（list_tools 成功）后即可在工具测试页验证工具。

## 验证

```bash
# 模拟一次 MCP 会话
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_music","arguments":{"query":"周杰伦"}}}' \
  | xiaozhi-music-mcp
```

## 说明

- 当前音乐库为内置模拟数据（10 首），“播放”仅更新播放状态并返回文本反馈；如需真实音频流，请将 `search_music_api` 替换为真实音乐 API。
- 日志输出到 stderr，不影响 STDIO 协议通信。
