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 |
新增工具，列出目录下可用的音频文件，便于先行确认。 |
开发说明
- 确保本地已安装
SDL/pygame所需的系统依赖。 - 在
music_file/文件夹中放置.mp3/.wav/.ogg文件。 - 运行
play-music-mcp，并在 MCP 客户端侧配置好服务器（STDIO 传输无需额外参数）。 - 若要发布到 PyPI：
- 更新
pyproject.toml中的版本号与项目信息。 - 运行
python -m build生成分发包。 - 使用
twine upload dist/*上传。
- 更新
许可证
本项目使用 MIT License，详见 LICENSE 文件。
1 maintainer
Metadata
1 maintainer
Release files for play-music-mcp 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| play_music_mcp-0.1.1.tar.gz | 8.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| play_music_mcp-0.1.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 17.7 kB
Release files / play_music_mcp-0.1.1.tar.gz
| Download URL | play_music_mcp-0.1.1.tar.gz |
|---|---|
| Size | 8.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0ea915104f0f3058f259073999682cd0ad6827060aef71e09a63c263b8ab8560
|
|
BLAKE2b-256 checksum How to use checksums |
3e60bf230d2536b56c17af2e8af95c59ccc7709306d44f0ccf6cfede802571ce
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Release files / play_music_mcp-0.1.1-py3-none-any.whl
| Download URL | play_music_mcp-0.1.1-py3-none-any.whl |
|---|---|
| Size | 9.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
98c9ac3a5f8d9f9c474cb36e25d27cfb73e346962d8ecafc0cbb6c52e9f49546
|
|
BLAKE2b-256 checksum How to use checksums |
e1b48f91e951dc5279ae375027a290c7ba1ecee4bf0ce87b4441d60fd87f28bf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
