https://github.com/davidteren/play-sound-mcp-server
Model Context Protocol server that provides audio playback functionality for AI agents. Play notification sounds when coding tasks complete. Early version/proof of concept - macOS only.
https://github.com/davidteren/play-sound-mcp-server
Last synced: 3 months ago
JSON representation
Model Context Protocol server that provides audio playback functionality for AI agents. Play notification sounds when coding tasks complete. Early version/proof of concept - macOS only.
- Host: GitHub
- URL: https://github.com/davidteren/play-sound-mcp-server
- Owner: davidteren
- License: mit
- Created: 2025-06-04T15:29:23.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-06-04T18:35:00.000Z (4 months ago)
- Last Synced: 2025-06-24T02:03:53.714Z (3 months ago)
- Language: Python
- Size: 123 KB
- Stars: 1
- Watchers: 0
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# MCP Play Sound Server
A Model Context Protocol (MCP) server that provides audio playback functionality for AI agents. This server enables AI agents to play sound notifications when coding tasks are completed.
> **⚠️ Early Version / Proof of Concept**
> This is an early implementation currently tested only on macOS. Future versions will support additional platforms.
## Features
- **Audio Notifications**: Play sound alerts when AI tasks complete
- **Default Sound**: Bundled notification sound for immediate use
- **Custom Audio**: Support for custom audio files (WAV, MP3, FLAC, OGG, M4A)
- **Intelligent Fallback**: Automatic fallback to default sound if custom audio fails
- **macOS Support**: Currently tested on macOS using AFPlay and SimpleAudio
## Installation & Setup
### Development Setup
1. **Clone and install**:
```bash
git clone
cd play-sound-mcp-server
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"
```
2. **Configure Claude Desktop**:
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"play-sound": {
"command": "uv",
"args": [
"--directory",
"/path/to/your/play-sound-mcp-server",
"run",
"mcp-server-play-sound"
]
}
}
}
```
3. **Test**: Restart Claude Desktop and ask: "Can you play a notification sound?"
## Configuration
Environment variables (optional):
- `CUSTOM_SOUND_PATH`: Path to custom audio file
- `VOLUME_LEVEL`: Playback volume (0.0-1.0, default: 0.8)
- `ENABLE_FALLBACK`: Enable fallback to default sound (default: true)
- `AUDIO_DEVICE`: Specific audio output device name (e.g., "Mac Studio Speakers")
## Available Tools
### `play_notification_sound`
Plays a notification sound to alert the user.
**Parameters:**
- `custom_sound_path` (optional): Path to custom audio file
- `message` (optional): Context message for the notification
### `get_audio_status`
Returns current audio system status and configuration.
### `test_audio_playback`
Tests audio playback functionality.
**Parameters:**
- `use_custom` (optional): Test with custom sound if configured
### `list_audio_devices`
Lists all available audio output devices on the system.
**Returns:**
- List of available audio devices with their properties
- Current configured device (if any)
- Default device information
## Development
### Prerequisites
- Python 3.10+
- uv (recommended) or pip
### Testing
```bash
pytest tests/
```
## License
MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic
- Python audio library maintainers