Kokoro TTS

Kokoro Text to Speech MCP Server lets you generate MP3 speech files locally with configurable voice, speed, and language, with optional upload to S3 for storage and distribution. It uses Kokoro’s TTS model and can convert WAV outputs to MP3, giving you a flexible, self-hosted TTS solution suitable for batch processing or on-demand speech generation.

How to use

You run the Kokoro TTS MCP server locally and connect to it with the MCP client to request speech synthesis. Start the server using UV as shown in the example, which runs the mcp-tts.py script from your local Kokoro TTS MCP directory. Configure your client to point to the server and optionally enable S3 uploads to store generated MP3s.

How to install

Prerequisites you need before installation: a Python runtime for any server-side scripts, and UV to manage the MCP process.

1. Clone or copy the Kokoro TTS MCP project to your local machine.

2. Download the Kokoro Onnx weights kokoro-v1.0.onnx and voices-v1.0.bin and place them in the same repository directory where you run the MCP server.

3. Install FFmpeg to enable WAV to MP3 conversion. On macOS: brew install ffmpeg.

4. Create a configuration file for MCP and include the Kokoro TTS MCP entry shown in the next section. Update paths, credentials, and bucket details to your environment.

Configuration

"kokoro-tts-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/toyourlocal/kokoro-tts-mcp",
        "run",
        "mcp-tts.py"
      ],
      "env": {
        "TTS_VOICE": "af_heart",
        "TTS_SPEED": "1.0",
        "TTS_LANGUAGE": "en-us",
        "AWS_ACCESS_KEY_ID": "",
        "AWS_SECRET_ACCESS_KEY": "",
        "AWS_REGION": "us-east-1",
        "AWS_S3_FOLDER": "mp3",
        "S3_ENABLED": "true",
        "MP3_FOLDER": "/path/to/mp3"
      } 
    }

MP3 File Management

The server generates MP3 files stored locally and can upload them to S3 if enabled. You control storage and cleanup with environment variables.

S3 and environment variables

Configure S3 and related behavior through the following environment variables in your .env file or when you start the MCP server: AWS credentials and bucket details, S3 folder, MP3 folder, and retention/deletion policies.

Using the TTS Client

The TTS client mcp_client.py lets you send synthesis requests to the Kokoro TTS MCP server. You can specify the text, voice, speed, and whether to upload to S3.

Additional notes

• Local MP3s are kept in the configured MP3_FOLDER and can be automatically deleted after a retention period. - S3 uploads can be disabled per request with the client option to skip S3. - Ensure FFmpeg is installed to support WAV to MP3 conversion.

Troubleshooting

If you encounter connection issues, verify the server binds to a reachable interface (0.0.0.0 or 127.0.0.1) and that the client connects to the correct host/port. Check that AWS credentials and the S3 bucket path are correctly set when enabling S3 uploads.

Security considerations

Limit access to the MCP server to trusted clients, protect AWS keys and endpoint URLs, and implement appropriate IAM policies to restrict S3 access. Regularly rotate credentials and review retention settings for stored MP3 files.

Available tools

mcp_client

Command-line client to send TTS requests to the Kokoro TTS MCP server, supporting text input, file input, voice, speed, and optional S3 upload.