play-music-mcp

# play-music-mcp 一个基于 [FastMCP](https://github.com/modelcontextprotocol/fastmcp) 和 `pygame` 的本地音乐播放 Model Context Protocol (MCP) 服务器。通过 MCP 工具可以管理播放列表、播放/暂停/上一首/下一首等控制动作，并提供音乐文件维护工具，适合在 Copilot / Claude Desktop 等遵循 MCP 标准的客户端中使用。 ## 功能特性 - 异步 MCP 工具：播放、暂停、恢复、停止、上一首、下一首、查看播放列表、列出本地音乐文件等。 - 后台播放线程：使用 `pygame.mixer` 长时间保持播放状态，支持单曲循环、列表循环、随机播放三种模式。 - 自动扫描 `music_file/` 目录，将匹配到的音频文件加载到播放列表。 - 标准输出 (STDIO) 传输：与大多数 MCP 客户端兼容，部署简单。 ## 安装 ```bash pip install play-music-mcp ``` 或在本地源码目录下构建并安装： ```bash cd 音乐 python -m build pip install dist/play_music_mcp-*.whl ``` ## 运行方式 包中提供了一个 `play-music-mcp` 控制台脚本，或直接运行模块： ```bash play-music-mcp --music-dir /absolute/path/to/music_dir # 等价于 python -m play_music --music-dir /absolute/path/to/music_dir ``` 通过 `--music-dir` 参数指定存放 `.mp3/.wav` 等文件的目录；若未提供，则默认使用当前工作目录下的 `music_file/`。服务器启动后会在 STDIO 上传输 MCP 消息，可直接由支持 MCP 的客户端托管。 ## MCP 工具列表 | 工具名 | 说明 | | --- | --- | | `play_musics_local` | 扫描 `music_file/` 并按设定模式播放（single/list/random）。 | | `pause_music` / `unpause_music` | 暂停或恢复当前曲目。 | | `stop_music` | 停止播放并重置内部状态。 | | `next_song` / `previous_song` | 在当前播放列表内切歌。 | | `get_playlist` | 返回当前播放列表及正在播放的歌曲。 | | `list_music_files` | 新增工具，列出目录下可用的音频文件，便于先行确认。 | ## 开发说明 1. 确保本地已安装 `SDL`/`pygame` 所需的系统依赖。 2. 在 `music_file/` 文件夹中放置 `.mp3/.wav/.ogg` 文件。 3. 运行 `play-music-mcp`，并在 MCP 客户端侧配置好服务器（STDIO 传输无需额外参数）。 4. 若要发布到 PyPI： - 更新 `pyproject.toml` 中的版本号与项目信息。 - 运行 `python -m build` 生成分发包。 - 使用 `twine upload dist/*` 上传。 ## 许可证 本项目使用 MIT License，详见 `LICENSE` 文件。