play-music-mcp 0.1.1

Local music playback MCP server powered by pygame and FastMCP.

play-music-mcp

一个基于 FastMCP 和 pygame 的本地音乐播放 Model Context Protocol (MCP) 服务器。通过 MCP 工具可以管理播放列表、播放/暂停/上一首/下一首等控制动作，并提供音乐文件维护工具，适合在 Copilot / Claude Desktop 等遵循 MCP 标准的客户端中使用。

功能特性

• 异步 MCP 工具：播放、暂停、恢复、停止、上一首、下一首、查看播放列表、列出本地音乐文件等。
• 后台播放线程：使用 pygame.mixer 长时间保持播放状态，支持单曲循环、列表循环、随机播放三种模式。
• 自动扫描 music_file/ 目录，将匹配到的音频文件加载到播放列表。
• 标准输出 (STDIO) 传输：与大多数 MCP 客户端兼容，部署简单。

安装

pip install play-music-mcp

或在本地源码目录下构建并安装：

cd 音乐
python -m build
pip install dist/play_music_mcp-*.whl

运行方式

包中提供了一个 play-music-mcp 控制台脚本，或直接运行模块：

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 文件。