Kokoro Text to Speech (TTS) MCP Server

Kokoro Text to Speech MCP server that generates .mp3 files with option to upload to S3.

Uses: https://huggingface.co/spaces/hexgrad/Kokoro-TTS

Configuration

Clone to a local repo.

Download the [Kokoro Onnx Weights](https://github.com/thewh1teagle/kokoro-onnx) for [kokoro-v1.0.onnx](https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/kokoro-v1.0.onnx) and [voices-v1.0.bin](https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/voices-v1.0.bin) and store in the same repo.

Add the following to your MCP configs. Update with your own values.

Install ffmmeg

This is needed to convert .wav to .mp3 files

For mac:

To run locally add these to your .env file. See env.example and copy to .env and modify with your own values.

Supported Environment Variables

`AWS_ACCESS_KEY_ID`: Your AWS access key ID

`AWS_SECRET_ACCESS_KEY`: Your AWS secret access key

`AWS_S3_BUCKET_NAME`: S3 bucket name

`AWS_S3_REGION`: S3 region (e.g., us-east-1)

`AWS_S3_FOLDER`: Folder path within the S3 bucket

`AWS_S3_ENDPOINT_URL`: Optional custom endpoint URL for S3-compatible storage

`MCP_HOST`: Host to bind the server to (default: 0.0.0.0)

`MCP_PORT`: Port to listen on (default: 9876)

`MCP_CLIENT_HOST`: Hostname for client connections to the server (default: localhost)

`DEBUG`: Enable debug mode (set to "true" or "1")

`S3_ENABLED`: Enable S3 uploads (set to "true" or "1")

`MP3_FOLDER`: Path to store MP3 files (default is 'mp3' folder in script directory)

`MP3_RETENTION_DAYS`: Number of days to keep MP3 files before automatic deletion

`DELETE_LOCAL_AFTER_S3_UPLOAD`: Whether to delete local MP3 files after successful S3 upload (set to "true" or "1")

`TTS_VOICE`: Default voice for the TTS client (default: af_heart)

`TTS_SPEED`: Default speed for the TTS client (default: 1.0)

`TTS_LANGUAGE`: Default language for the TTS client (default: en-us)

Running the Server Locally

Preferred method use UV

Using the TTS Client

The `mcp_client.py` script allows you to send TTS requests to the server. It can be used as follows:

Connection Settings

When running the server and client on the same machine:

Server should bind to `0.0.0.0` (all interfaces) or `127.0.0.1` (localhost only)

Client should connect to `localhost` or `127.0.0.1`

Basic Usage

Reading Text from a File

Customizing Voice and Speed

Disabling S3 Upload

Command-line Options

MP3 File Management

The TTS server generates MP3 files that are stored locally and optionally uploaded to S3. You can configure how these files are managed:

Local Storage

Set `MP3_FOLDER` in your `.env` file to specify where MP3 files are stored

Files are kept in this folder unless automatically deleted

Automatic Cleanup

Set `MP3_RETENTION_DAYS=30` (or any number) to automatically delete files older than that number of days

Set `DELETE_LOCAL_AFTER_S3_UPLOAD=true` to delete local files immediately after successful S3 upload

S3 Integration

Enable/disable S3 uploads with `S3_ENABLED=true` or `DISABLE_S3=true`

Configure AWS credentials and bucket settings in the `.env` file

S3 uploads can be disabled per-request using the client's `--no-s3` option

Kokoro TTS