mp3 player server

MP3播放器 MCP服务器

这是一款MCP服务器，可播放、暂停指定文件夹内的MP3文件，并可获取文件列表。

主要功能

• 🎵 播放/停止MP3文件
• 📋 播放列表功能（全部播放）
• 🎲 随机播放
• 🔄 自动播放（一首歌结束后自动播放下一首）
• ⏭️ 跳到下一首歌
• ⏮️ 返回上一首
• 🔁 重复模式（整首歌曲重复、单曲重复）

安装步骤

1. 安装必要的库

pip install mcp pygame --break-system-packages

2. 文件配置

mp3_player_server.py 将其保存到任意位置。 例：~/Documents/mcp-servers/mp3_player_server.py

3. 赋予执行权限（视需要而定）

chmod +x ~/Documents/mcp-servers/mp3_player_server.py

4. MCP设置

Cursor的情况（推荐）：

~/.cursor/mcp.json 进行编辑

{
  "mcpServers": {
    "mp3-player": {
      "command": "python3",
      "args": [
        "/Users/yourname/workspace/mp3_player_server/mp3_player_server/mp3_player_server.py"
      ],
      "env": {
        "MUSIC_FOLDER": "/Users/yourname/Music"
      }
    }
  }
}

在Claude Desktop的情况下：

设置文件位置：

• Mac： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows（操作系统）： %APPDATA%\Claude\claude_desktop_config.json

设置示例（使用pyenv时）：

{
  "mcpServers": {
    "mp3-player": {
      "command": "/Users/yourname/.pyenv/versions/3.11.4/bin/python3",
      "args": [
        "/Users/yourname/workspace/mp3_player_server/mp3_player_server/mp3_player_server.py"
      ],
      "env": {
        "MUSIC_FOLDER": "/Users/yourname/Music"
      }
    }
  }
}

⚠️ 重要注意事项：

• args 这部分 mp3_player_server.py 请更改为实际路径
• MUSIC_FOLDER 请将其更改为包含MP3文件的文件夹路径
• 如果使用pyenv的情况下Claude Desktoppython3因为尝试使用系统自带的Python命令，所以pygame可能没有安装。此时command请指定pyenv的完整路径（例如： /Users/yourname/.pyenv/versions/3.11.4/bin/python3）

- 确认自己的pyenv Python路径： which python3

5. 重启

为使设置生效，请执行以下操作之一：

• 光标完全退出Cursor并重新启动
• Claude Desktop（中文可译为“Claude桌面版”或保持原样，具体取决于语境和是否需要意译）彻底关闭应用（包括任务栏中的）并重新启动

使用方法

在与Claude/Cursor对话时，您可以提出以下请求：

基本操作

获取MP3文件列表

音楽フォルダーにあるMP3ファイルを教えて

播放MP3文件

"song.mp3" を再生して

按顺序播放整首曲子

全部の曲を再生して

随机播放

全部の曲をシャッフルして再生して

停止播放

音楽を停止して

确认再生状态

今何が再生されているか教えて

播放列表操作

跳到下一首歌

次の曲にして

返回上一首歌

前の曲に戻して

循环模式设置

顺序播放模式

順番再生モードにして

随机播放模式

シャッフルモードにして

整首歌循环播放模式

全曲リピートにして

单曲循环模式

1曲リピートにして

可用工具

基本工具

1. 列出MP3文件列出音乐文件夹内的所有MP3文件
2. 播放MP3播放指定的MP3文件
3. 停止播放停止当前播放
4. 获取播放状态获取播放状态（包括播放列表信息）

播放列表工具

1. 播放全部播放整首曲目（含随机播放选项）
2. 下一曲跳到下一首歌
3. 上一曲返回上一曲
4. 设置播放模式设置循环模式

- sequential顺序播放 - shuffle随机播放 - repeat_all整首歌循环 - repeat_one单曲循环

自动播放功能

曲目播放结束后，会根据设定的播放模式自动播放下一首曲目。

项目构成

mp3_player_server/
├── mp3_player_server.py      # メインサーバー（MCPプロトコル実装）
├── README.md                  # このファイル
└── claude_desktop_config.json # 設定ファイルの例（参考用）

故障排除

当MCP服务器未被识别时

1. 彻底关闭Cursor/Claude Desktop（包括任务栏中的）
2. 确认设置文件的JSON是否正确（逗号、括号等）
3. 确认文件路径是否正确
4. 查看日志

- 光标：DevTools 控制台 - Claude Desktop（桌面版） ~/Library/Logs/Claude/ (Mac) / %APPDATA%\Claude\logs\ （Windows）

当出现“ModuleNotFoundError: No module named 'pygame'”错误时

原因Claude Desktop正在使用不同的Python解释器

解决方法:

1. 确认已安装pygame的Python路径：

   which python3
   # 例: /Users/yourname/.pyenv/shims/python3

   python3 -c "import sys; print(sys.executable)"
   # 例: /Users/yourname/.pyenv/versions/3.11.4/bin/python3

1. 在Claude Desktop的设置文件中command改为完整路径：

   "command": "/Users/yourname/.pyenv/versions/3.11.4/bin/python3"

1. 重启Claude Desktop

音乐无法播放时

1. 确认MUSIC_FOLDER的路径是否正确
2. 确认文件夹内是否存在.mp3文件
3. 如果文件名中包含日语或特殊字符，可能会出现编码问题

当pygame的系统依赖项缺失时

# システムの依存関係をインストール（Ubuntu/Debianの場合）
sudo apt-get install python3-pygame

# macOSの場合
brew install sdl2 sdl2_mixer

定制

增加应对形式

代码中的 *.mp3 也可以适配其他形式：

def get_mp3_files() -> list[str]:
    audio_files = []
    for pattern in ["*.mp3", "*.wav", "*.ogg"]:
        for file in MUSIC_FOLDER.glob(pattern):
            audio_files.append(file.name)
    return sorted(audio_files)

搜索子文件夹

def get_mp3_files() -> list[str]:
    mp3_files = []
    for file in MUSIC_FOLDER.rglob("*.mp3"):  # rglob で再帰的に検索
        mp3_files.append(str(file.relative_to(MUSIC_FOLDER)))
    return sorted(mp3_files)

使用示例

情景1：将整首曲目作为背景音乐随机播放

ユーザー: 全部の曲をシャッフルして再生して
AI: 🎲 シャッフル再生を開始しました！

情景2：为工作需要循环播放全部曲目

ユーザー: 全曲リピートモードにして
AI: 🔁 全曲リピートモードに設定しました
ユーザー: 全部の曲を再生して
AI: 🎵 再生を開始しました（曲が終わると自動で次へ）

情景3：播放特定曲目并进行控制

ユーザー: かぐや姫を再生して
AI: 🎵 再生開始
ユーザー: 次の曲にして
AI: ⏭️ 次の曲にスキップしました

技术规格

• 语言Python 3.11+
• 依赖关系MCP，Pygame
• 对应格式MP3
• 协议MCP（模型上下文协议）
• 通信方式stdio（标准输入输出）
• 自动播放在异步任务中进行监控
• 支持日语支持文件名中包含日语和表情符号的文件

已知问题和限制条件

限制事项

• 对应格式目前仅支持MP3文件（不支持WAV、OGG等格式）
• 子文件夹默认情况下，仅搜索指定文件夹下的MP3文件（不搜索子文件夹）
• 同时播放无法同时播放多首曲目
• 音量调节当前版本没有音量调节功能
• 保存播放列表没有播放列表保存功能（会话结束时重置）

已知问题

• pyenv与Claude Desktop若在Claude Desktop中使用pyenv，则需要明确指定Python路径（请参阅上述故障排除部分）
• 长文件名极长的文件名（255个字符以上）可能会导致显示错乱
• 特殊字符包含某些特殊字符（除表情符号外）的文件名可能会出现问题

未来功能追加候选

• 音量调节功能
• 支持WAV、OGG、FLAC等其他音频格式
• 播放列表的保存与加载功能
• 均衡器功能
• 搜索回放位置功能

许可证

麻省理工学院许可证