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音頻庫的維護者們。