play-sound-mcp-server

🚀 MCP播放声音服务器

MCP播放声音服务器是一个基于模型上下文协议（MCP）的服务器，它为AI智能体提供音频播放功能。借助该服务器，AI智能体在完成编码任务时能够播放声音通知，极大地提升了用户体验。

⚠️ 重要提示

此为早期版本/概念验证，目前仅在macOS上进行了测试，后续版本将支持更多平台。

✨ 主要特性

• 音频通知：当AI任务完成时播放声音警报。
• 默认音效：自带通知音效，可立即使用。
• 自定义音频：支持自定义音频文件（WAV、MP3、FLAC、OGG、M4A）。
• 智能回退：若自定义音频播放失败，自动回退到默认音效。
• macOS支持：目前已在macOS上使用AFPlay和SimpleAudio进行测试。

📦 安装指南

开发环境设置

1. 克隆并安装项目：

git clone <repository-url>
cd play-sound-mcp-server
python -m venv .venv
source .venv/bin/activate  # 在Windows上使用: .venv\Scripts\activate
pip install -e ".[dev]"

2. 配置Claude桌面应用： 在claude_desktop_config.json文件中添加以下内容：

{
  "mcpServers": {
    "play-sound": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/play-sound-mcp-server",
        "run",
        "mcp-server-play-sound"
      ]
    }
  }
}

3. 测试配置：重启Claude桌面应用，然后询问：“你能播放通知声音吗？”

📚 详细文档

配置

可通过以下环境变量进行配置（可选）：

• CUSTOM_SOUND_PATH：自定义音频文件的路径。
• VOLUME_LEVEL：播放音量（范围0.0 - 1.0，默认值：0.8）。
• ENABLE_FALLBACK：启用回退到默认音效的功能（默认值：true）。
• AUDIO_DEVICE：指定音频输出设备名称（例如，“Mac Studio Speakers”）。

可用工具

play_notification_sound

用于播放通知声音以提醒用户。 参数：

• custom_sound_path（可选）：自定义音频文件的路径。
• message（可选）：通知的上下文消息。

get_audio_status

返回当前音频系统的状态和配置信息。

test_audio_playback

测试音频播放功能。 参数：

• use_custom（可选）：若已配置自定义音效，则使用自定义音效进行测试。

list_audio_devices

列出系统上所有可用的音频输出设备。 返回值：

• 包含可用音频设备及其属性的列表。
• 当前配置的设备（如果有）。
• 默认设备信息。

🔧 技术细节

开发前提条件

• Python 3.10 及以上版本。
• uv（推荐）或pip。

测试

pytest tests/

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE 文件。

致谢

• 模型上下文协议 由Anthropic提供。
• Python音频库的维护者们。