Kokoro Text to Speech MCP Server

Overview

The Kokoro Text to Speech (TTS) MCP Server is a tool that generates .mp3 files from text input, with the option to upload these files to Amazon S3. It leverages the Kokoro TTS model hosted on Hugging Face Spaces for text-to-speech conversion.

Tools and Dependencies

• Kokoro TTS Model: Kokoro-TTS on Hugging Face
• FFmpeg: Required for converting .wav files to .mp3.
• Installation on Mac:
  shell brew install ffmpeg
• Kokoro Onnx Weights: Download the weights from kokoro-onnx repository.

Configuration

1. Clone the repository locally.
2. Download the Kokoro Onnx Weights and place them in the repository.
3. Update the MCP configuration with the following settings:
   json "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" } }

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)

Usage

Running the Server Locally

To start the server using UV:

uv run mcp-tts.py

Using the TTS Client

The mcp_client.py script allows you to send TTS requests to the server.

Basic Usage

python mcp_client.py --text "Hello, world!"

Reading Text from a File

python mcp_client.py --file my_text.txt

Customizing Voice and Speed

python mcp_client.py --text "Hello, world!" --voice "en_female" --speed 1.2

Disabling S3 Upload

python mcp_client.py --text "Hello, world!" --no-s3

Command-line Options

python mcp_client.py --help

MP3 File Management

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.

License

This project is licensed under the Apache-2.0 license.