Kokoro TTS

What is Kokoro Text to Speech (TTS) MCP Server?

Kokoro Text to Speech (TTS) MCP Server is a Python-based application that converts text into MP3 audio files. It offers the functionality to optionally upload these generated MP3s to an Amazon S3 bucket, providing a convenient solution for managing and distributing audio content.

How to use Kokoro Text to Speech (TTS) MCP Server?

To use Kokoro TTS MCP Server, you need to:

Clone the repository: Obtain the project files by cloning the GitHub repository.
Download ONNX weights: Download the kokoro-v1.0.onnx and voices-v1.0.bin files from the Kokoro Onnx Weights repository and place them in the same directory as the cloned project.
Install FFmpeg: Install FFmpeg on your system, as it is required for converting WAV files to MP3s. For macOS, you can use brew install ffmpeg.
Configure environment variables: Set up necessary environment variables in an .env file (or directly in your MCP configs) for AWS credentials (if using S3), S3 bucket details, and other server settings like default voice, speed, and language.
Run the server: Execute the server using uv run mcp-tts.py.
Use the TTS Client: Utilize the mcp_client.py script to send text-to-speech requests to the server. You can provide text directly, read from a file, customize voice and speed, and control S3 uploads.

Key Features of Kokoro Text to Speech (TTS) MCP Server

Text-to-Speech Conversion: Converts input text into high-quality MP3 audio files.
S3 Integration: Optional automatic upload of generated MP3 files to Amazon S3 for cloud storage and distribution.
Configurable Settings: Allows customization of default TTS voice, speech speed, and language.
Local MP3 Storage: Stores generated MP3 files locally with configurable retention policies.
Automatic Cleanup: Supports automatic deletion of local MP3 files after a specified number of days or immediately after S3 upload.
Command-line Client: Provides a convenient Python client for interacting with the TTS server, supporting various options for text input and output control.
Environment Variable Support: Easy configuration through environment variables for seamless deployment and management.

Use Cases of Kokoro Text to Speech (TTS) MCP Server

Content Creation: Generate audio versions of articles, blog posts, or e-books for accessibility or podcasting.
Voice Assistants: Develop custom voice responses for applications or smart home devices.
E-learning: Create audio lectures or study materials for educational platforms.
Accessibility: Provide audio alternatives for visually impaired users to access text content.
Automated Notifications: Generate spoken notifications or alerts for various systems.
Interactive Voice Response (IVR) Systems: Create dynamic audio prompts for telephone-based systems.

FAQ from Kokoro Text to Speech (TTS) MCP Server

Q: What is FFmpeg needed for? A: FFmpeg is required to convert the generated WAV audio files into MP3 format.

Q: How do I configure S3 uploads? A: You need to set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_S3_BUCKET_NAME, and AWS_S3_REGION in your environment variables or MCP configs. You can also enable/disable S3 uploads using the S3_ENABLED variable or the client's --no-s3 option.

Q: Can I change the default voice or speed? A: Yes, you can set TTS_VOICE and TTS_SPEED environment variables for default values, or specify them per request using the client's --voice and --speed options.

Q: How are MP3 files managed locally? A: MP3 files are stored in the directory specified by MP3_FOLDER. You can configure MP3_RETENTION_DAYS to automatically delete old files or DELETE_LOCAL_AFTER_S3_UPLOAD to remove them after successful S3 upload.

Q: How do I run the server and client on the same machine? A: Ensure the server binds to 0.0.0.0 or 127.0.0.1 and the client connects to localhost or 127.0.0.1.

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 for kokoro-v1.0.onnx and voices-v1.0.bin and store in the same repo.

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

  "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"
      } 
    }

Install ffmmeg

This is needed to convert .wav to .mp3 files

For mac:

brew install ffmpeg

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

uv run mcp-tts.py

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

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

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 Overview