Kokoro Tts MCP

What mberg/kokoro-tts-mcp MCP server does

Audio is generated locally from the Kokoro ONNX model and voice data, rather than being sent to a hosted speech API. The resulting files are written to a local MP3 directory and may also be uploaded to an S3 bucket.

The default synthesis settings include the af_heart voice, speed 1.0, and the en-us language. These defaults can be changed through environment variables. The accompanying client can submit text directly, read text from a file, select a voice, change playback speed, or disable S3 upload for an individual request.

How it works

The repository must contain two Kokoro model files: kokoro-v1.0.onnx and voices-v1.0.bin. The server loads these local assets to produce speech. FFmpeg is also needed to convert the generated WAV audio into MP3 format; on macOS, the documented installation command is brew install ffmpeg.

A local process can be started with uv run mcp-tts.py. The MCP configuration shown by the project runs that script through uv from the cloned repository directory. The server can bind to all interfaces or localhost, with a default port of 9876 for the network configuration described in the README.

When S3 support is enabled, the server uses configured AWS credentials, bucket settings, region, folder, and optional endpoint URL. S3-compatible services can therefore be configured through an alternate endpoint. Local files can remain in the MP3 directory, be removed after a successful upload, or be cleaned up after a configured retention period.

Setup and configuration

Clone the repository, download the referenced Kokoro ONNX weights, and place both model files in the repository. Install FFmpeg separately before starting the server. Copy the example environment file to .env, then set values appropriate for local storage and, if needed, S3.

Important settings include MP3_FOLDER for local output, TTS_VOICE, TTS_SPEED, and TTS_LANGUAGE for synthesis defaults, and S3_ENABLED for upload behavior. S3 configuration uses access credentials, a bucket name, a region, and an optional folder or custom endpoint. MP3_RETENTION_DAYS controls age-based deletion, while DELETE_LOCAL_AFTER_S3_UPLOAD controls removal after a successful transfer.

Tools and capabilities

mberg/kokoro-tts-mcp MCP server supports these documented workflows:

• Generate an MP3 from text.
• Read source text from a file through the supplied client.
• Override the voice and speed for a request.
• Upload generated audio to S3 when enabled.
• Disable S3 upload for a specific client request.
• Keep local files, remove them after upload, or delete older files automatically.

Limitations and notes

The material does not list the MCP tool names or provide a hosted endpoint. Operation depends on locally downloaded model files and an FFmpeg installation. S3 uploads require the relevant AWS or S3-compatible configuration, but the documented client can bypass S3 for a request. The README presents local execution and configuration examples rather than a packaged registry installation command.