Piper TTS MCP Server

A Model Context Protocol (MCP) server that provides Text-to-Speech (TTS) capabilities using the Piper engine. This server allows AI models to "speak" by generating high-quality voice messages from text.

Features

• High-Quality TTS: Uses Piper for fast, local speech synthesis.
• MCP Integration: Compatible with any MCP client supporting HTTP transport.
• Audio Streaming: Returns a URL to the generated audio in Ogg Opus format (optimized for web/mobile).
• Automatic Model Management: Automatically downloads requested models if they are not present locally.
• LRU Caching: Stores the last 3 generated audio files in memory for retrieval.

Installation & Setup

Prerequisites

• Docker and Docker Compose
• Or Python 3.12 with uv

Using Docker (Recommended)

1. Build the image:

   docker compose build
   

2. Start the server:

   docker compose up piper-mcp
   

   The server will be running at http://localhost:8000.

Local Development

1. Install dependencies:

   uv sync
   

2. Run the server:

   # Use HTTP transport by default
   export MCP_TRANSPORT=http
   uv run server.py
   

MCP Server Connection

To connect, use the following configuration (HTTP transport):

{
  "mcpServers": {
    "piper-tts": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Testing

To run the automated tests using Docker (uses the test profile):

docker compose --profile test up tests

Or locally:

pytest tests/

MCP Tool

After connecting, the following tool will be available:

• speak: Generates a voice message from text.
  • Arguments: text (string) — the text to speak.
  • Result: A JSON object containing status, audio_url, and metadata (size, format).

Model Selection

The voice model is selected using the MODEL environment variable.

• Default Model: ru_RU-denis-medium.
• Logic:
  1. At startup, the server checks for .onnx and .onnx.json files in the working directory.
  2. If not found, it automatically downloads them from the official Piper repository.
  3. Change the MODEL value in docker-compose.yml to switch voices.

Project Repositories

• Piper Engine: https://github.com/OHF-Voice/piper1-gpl
• Piper Voices (Model List): https://github.com/OHF-Voice/piper1-gpl/blob/main/docs/VOICES.md — check this repository to see all available voices and their names.