README.md•4.63 kB
# 🎤 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**