# MCP Audio Server π
*[English](README.md) | [δΈζ](README_CN.md)*
A powerful Model Context Protocol (MCP) server that provides text-to-speech and audio playback capabilities for Claude Desktop and other MCP clients.
## β¨ Features
- **π£οΈ High-Quality TTS**:
- **Smart Language Detection**: Automatically uses Google's TTS for high-quality Chinese speech and falls back to the system's TTS for other languages.
- **Voice Selection**: For non-Chinese text, list and select from various system-installed voices.
- **Customizable Speech**: Adjust rate and volume for a tailored listening experience.
- **π΅ Audio File Playback**: Play various audio formats (WAV, MP3, OGG, etc.).
- **βΉοΈ Audio Control**: Stop playback and get real-time audio status.
- **π MCP Compliant**: Fully compatible with Claude Desktop and MCP specification 2024-11-05.
- **π‘οΈ Error Handling**: Robust error handling and validation.
- **π Status Monitoring**: Real-time audio system status and playback information.
## π Quick Start
### Prerequisites
- Python 3.8+
- Claude Desktop (for MCP integration)
- System audio capabilities
### Installation
1. **Clone the repository:**
```bash
git clone https://github.com/yourusername/mcp-audio-server.git
cd mcp-audio-server
```
2. **Install dependencies:**
```bash
pip install -r requirements.txt
```
3. **Configure Claude Desktop:**
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"audio-server": {
"command": "/path/to/your/python",
"args": ["/path/to/mcp-audio-server/audio_server.py"]
}
}
}
```
4. **Restart Claude Desktop** and start using audio features!
## π οΈ Available Tools
| Tool | Description | Parameters |
|------|-------------|------------|
| `speak_text` | Convert text to speech. Automatically uses Google TTS for Chinese. | `text` (required), `rate` (optional), `volume` (optional), `voice_id` (optional, for non-Chinese) |
| `list_voices` | List available TTS voices for non-Chinese languages. | None |
| `play_audio_file` | Play an audio file. | `file_path` (required), `volume` (optional) |
| `stop_audio` | Stop current audio playback. | None |
| `get_audio_status` | Get audio system status. | None |
## π Usage Examples
### Text-to-Speech (Chinese)
```
"θ―·η¨θ―ι³θ―΄εΊ 'δ½ ε₯½οΌδΈη'"
```
*This will automatically use Google TTS for a natural-sounding voice.*
### Text-to-Speech (English, with a specific voice)
1. **First, list available voices:**
```
"List all available voices"
```
2. **Then, use a specific voice ID from the list:**
```
"Use the voice with ID 'com.apple.speech.synthesis.voice.daniel' to say 'Hello, this is a test.'"
```
### Play Audio File
```
"Play the audio file at /path/to/music.mp3"
```
### Stop Audio
```
"Stop the current audio playback"
```
### Check Status
```
"What's the current audio status?"
```
## π§ͺ Testing
Run the comprehensive test suite:
```bash
# Test all MCP methods
python test_all_mcp_methods.py
# Test Claude Desktop format compatibility
python test_claude_desktop_format.py
# Test audio functionality
python test_audio_server.py
# Interactive testing mode
python audio_server.py --interactive
```
## π Project Structure
```
mcp-audio-server/
βββ audio_server.py # Main MCP server
βββ requirements.txt # Python dependencies
βββ README.md # English documentation (default)
βββ README_CN.md # Chinese documentation
βββ .gitignore # Git ignore rules
βββ tests/ # Test files
β βββ test_*.py # Various tests
β βββ validate_*.py # Validation scripts
βββ examples/ # Configuration examples
β βββ claude_desktop_config.json
β βββ other config files
βββ scripts/ # Utility scripts
β βββ install_and_setup.sh
β βββ other shell scripts
βββ docs/ # Additional documentation
βββ INTEGRATION_GUIDE.md # Integration guide
βββ USAGE_GUIDE.md # Usage guide
βββ FINAL_INTEGRATION_REPORT.md
```
## π§ Configuration
### Claude Desktop Configuration
The server integrates seamlessly with Claude Desktop. Make sure your configuration file is properly set up:
**Location:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
**Example configuration:**
```json
{
"mcpServers": {
"audio-server": {
"command": "/Users/yourusername/miniconda3/envs/mcp_agent/bin/python",
"args": ["/path/to/mcp-audio-server/audio_server.py"]
}
}
}
```
## π Troubleshooting
### Common Issues
1. **Audio not playing**: Check system audio settings and permissions
2. **TTS not working**: Ensure pyttsx3 is properly installed
3. **MCP connection issues**: Verify Claude Desktop configuration path
4. **Permission errors**: Check file permissions for audio files
### Debug Mode
Run in interactive mode for debugging:
```bash
python audio_server.py --interactive
```
## π€ Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request
## π License
This project is licensed under the MIT License - see the LICENSE file for details.
## π Acknowledgments
- Built with the Model Context Protocol (MCP)
- Uses pyttsx3 for text-to-speech
- Uses pygame for audio playback
- Compatible with Claude Desktop
## π Support
If you encounter any issues or have questions:
1. Check the troubleshooting section
2. Review the integration guide
3. Open an issue on GitHub
4. Check Claude Desktop documentation
---
**Made with β€οΈ for the MCP community**
