kokoro-tts-mcp

# Kokoro TTS MCP Server A Model Context Protocol (MCP) server that provides text-to-speech capabilities using the Kokoro TTS engine. This server exposes TTS functionality through MCP tools, making it easy to integrate speech synthesis into your applications. ## Prerequisites - Python 3.10 or higher - `uv` package manager ## Installation 1. First, install the `uv` package manager: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` 2. Clone this repository and install dependencies: ```bash uv venv source .venv/bin/activate # On Windows, use: .venv\Scripts\activate uv pip install . ``` ## Features - Text-to-speech synthesis with customizable voices - Adjustable speech speed - Support for saving audio to files or direct playback - Cross-platform audio playback support (Windows, macOS, Linux) - Optional OpenAI-compatible remote backend (e.g. [kokoro-fastapi](https://github.com/remsky/Kokoro-FastAPI)) to offload synthesis to a GPU box ## Usage The server provides a single MCP tool `generate_speech` with the following parameters: - `text` (required): The text to convert to speech - `voice` (optional): Voice to use for synthesis (default: "af_heart") - `speed` (optional): Speech speed multiplier (default: 1.0) - `save_path` (optional): Directory to save audio files - `play_audio` (optional): Whether to play the audio immediately (default: False) ### Example Usage ```python from mcp.client import Client async with Client() as client: await client.connect("kokoro-tts") # Generate and play speech result = await client.call_tool( "generate_speech", { "text": "Hello, world!", "voice": "af_heart", "speed": 1.0, "play_audio": True } ) ``` ## Remote backend (OpenAI-compatible) By default the server runs Kokoro locally. If you already run an OpenAI-compatible TTS endpoint such as [kokoro-fastapi](https://github.com/remsky/Kokoro-FastAPI) (handy for running on a GPU), point the server at it with environment variables — no local `torch`/`kokoro` needed: | Variable | Default | Description | |----------|---------|-------------| | `KOKORO_BASE_URL` | _(unset)_ | OpenAI-compatible base URL, e.g. `http://localhost:8880/v1`. When set, synthesis is sent here instead of running locally. | | `KOKORO_API_KEY` | `not-needed` | Bearer token, if your endpoint requires one. | | `KOKORO_MODEL` | `kokoro` | Model name passed to the endpoint. | Under the hood this calls `POST {KOKORO_BASE_URL}/audio/speech` with the standard OpenAI payload (`model`, `input`, `voice`, `speed`, `response_format: wav`). ## Docker ```bash docker build -t kokoro-tts-mcp . docker run --rm -i kokoro-tts-mcp ``` To use a remote backend instead of bundling Kokoro: ```bash docker run --rm -i -e KOKORO_BASE_URL=http://host.docker.internal:8880/v1 kokoro-tts-mcp ``` ## Dependencies - kokoro >= 0.8.4 - mcp[cli] >= 1.3.0 - soundfile >= 0.13.1 - httpx >= 0.27.0 ## Platform Support Audio playback is supported on: - Windows (using `start`) - macOS (using `afplay`) - Linux (using `aplay`) ## MCP Configuration Add the following configuration to your MCP settings file: ```json { "mcpServers": { "kokoro-tts": { "command": "/Users/giannisan/pinokio/bin/miniconda/bin/uv", "args": [ "--directory", "/Users/giannisan/Documents/Cline/MCP/kokoro-tts-mcp", "run", "tts-mcp.py" ] } } } ``` ## License [MIT](LICENSE) © Gianni Sanrochman