MCP Play Sound Server

MCP 播放声音服务

一个为 AI Agent 提供音频播放功能的 Model Context Protocol（MCP）服务。此服务可让 AI Agent 在编码任务完成时播放声音通知。

⚠️ 早期版本 / 概念验证 这是一个早期实现，目前仅在 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  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"

2. 配置 Claude Desktop： 将以下内容添加到 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 Desktop 并询问：“可以播放通知音效吗？”

配置

环境变量（可选）：

• 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 提供的 Model Context Protocol
• Python 音频库维护者