Which integrations are available for this server?

Automatically uses [Google](/mcp/servers/integrations/google)'s TTS (text-to-speech) service for high-quality Chinese language speech synthesis

MCP Audio Server 🔊

English

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

Clone the repository:

git clone https://github.com/yourusername/mcp-audio-server.git cd mcp-audio-server

Install dependencies:

pip install -r requirements.txt

Configure Claude Desktop: Add to your claude_desktop_config.json:

{ "mcpServers": { "audio-server": { "command": "/path/to/your/python", "args": ["/path/to/mcp-audio-server/audio_server.py"] } } }

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)

First, list available voices:
"List all available voices"
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:

# 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:

{ "mcpServers": { "audio-server": { "command": "/Users/yourusername/miniconda3/envs/mcp_agent/bin/python", "args": ["/path/to/mcp-audio-server/audio_server.py"] } } }

🐛 Troubleshooting

Common Issues

Audio not playing: Check system audio settings and permissions
TTS not working: Ensure pyttsx3 is properly installed
MCP connection issues: Verify Claude Desktop configuration path
Permission errors: Check file permissions for audio files

Debug Mode

Run in interactive mode for debugging:

python audio_server.py --interactive

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
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:

Check the troubleshooting section
Review the integration guide
Open an issue on GitHub
Check Claude Desktop documentation

Made with ❤️ for the MCP community

MCP Audio Server