Piper TTS MCP Server

# 🎤 Piper TTS MCP Server A **Model Context Protocol (MCP)** server that integrates [Piper TTS](https://github.com/rhasspy/piper) for high-quality text-to-speech functionality. This server provides a `speak` tool that converts text to speech and plays it directly through your speakers with customizable volume control. ## ✨ Features - 🔊 **High-quality text-to-speech** using Piper TTS - 🎚️ **Volume control** (0.01 to 1.00) - ⚡ **Memory-based audio playback** (no temporary files) - 🔧 **Customizable voice parameters** (speaker, speed, voice variation) - 🚀 **Fast and lightweight** MCP integration - 🔇 **Silent operation** (no console output) ## 📋 Requirements **⚠️ Important Prerequisites:** - **Python 3.12+** installed on your system - **Piper TTS service** running on `localhost:5000` You can set this up using the included Docker configuration or by running Piper TTS separately. ## 🚀 Quick Start ### 1. 🐳 Start Piper TTS Service Clone this repo and start the TTS service: ```bash git clone https://github.com/CryptoDappDev/piper-tts-mcp.git cd piper-tts-mcp ``` **Option A: Using Docker Compose (Recommended)** ```bash docker compose up -d ``` **Option B: Using Docker Build** ```bash docker build -t piper-tts-mcp . docker run -p 5000:5000 piper-tts-mcp ``` ### 2. 🔧 Configure MCP Client Add the server to your MCP configuration (e.g., `.mcp.json` for Claude Desktop): ```json { "mcpServers": { "speak": { "command": "uv", "args": [ "--directory", "/path/to/your/piper-tts-mcp", "run", "server.py" ] } } } ``` ### 3. 🎉 Enjoy! The `speak` tool is now available in your MCP client! ## 🛠️ Usage The MCP server provides a `speak` tool with the following parameters: | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `text` | string | *required* | Text to convert to speech | | `speaker_id` | int | 0 | Voice speaker ID | | `length_scale` | float | 1.1 | Speech speed (lower = faster) | | `noise_scale` | float | 0.667 | Voice variation control | | `noise_w_scale` | float | 0.333 | Pronunciation variation | | `volume` | float | 0.15 | Volume level (0.01 to 1.00) | ### Example Usage ```python # Basic usage speak("Hello, world!") # With custom volume speak("This is louder!", volume=0.5) # With custom voice settings speak("Fast and varied speech", length_scale=0.8, volume=0.3, noise_scale=0.8) ``` ## 🔧 Development ### Dependencies - Python 3.12+ - `mcp[cli]` - MCP framework - `requests` - HTTP client for TTS API - `pygame` - Audio playback ### Local Development ```bash # Install dependencies uv sync # Run the server uv run server.py ``` ## 📦 Docker Configuration The included Docker setup provides: - **Piper TTS service** on port 5000 - **Pre-configured voice models** - **Automatic startup** ## 🎙️ Voice Models The default voice model used in this repository is **`en_GB-cori-high`** (British English, female voice). ### 🔍 Exploring Voice Options - **Voice Samples**: Listen to different voice models at [Piper Voice Samples](https://rhasspy.github.io/piper-samples/) - **Piper Documentation**: Learn more about Piper TTS at [rhasspy/piper](https://github.com/rhasspy/piper?tab=readme-ov-file) ### 🛠️ Changing Voice Models To use a different voice model: 1. **Choose a voice** from the [voice samples page](https://rhasspy.github.io/piper-samples/) 2. **Update the Dockerfile** - Replace `en_GB-cori-high` with your chosen voice model: ```dockerfile # Download your preferred voice model RUN python3 -m piper.download_voices your-chosen-voice-model # Update the server command CMD ["sh", "-c", "python3 -m piper.http_server -m your-chosen-voice-model"] ``` 3. **Rebuild the Docker image**: ```bash docker build -t piper-tts-mcp . docker compose up -d ``` ### 🎨 Creating Custom Voices Creating your own custom voice requires additional effort and research. Please refer to the [Piper documentation](https://github.com/rhasspy/piper) for guidance on voice training and customization. ## 🤝 Contributing Contributions are welcome! Please feel free to submit issues and pull requests. ## 📄 License This project is open source and available under the [MIT License](LICENSE). ## 🙏 Acknowledgments - [Piper TTS](https://github.com/rhasspy/piper) - Fast, local neural text to speech - [Model Context Protocol](https://modelcontextprotocol.io/) - Standardized protocol for AI model interactions --- **Made with ❤️ for the MCP community**