playbooks
Learn Cursor Rules Windsurf Rules MCPs Modes
Log in

Kokoro TTS MCP server

Converts text to speech using the Kokoro TTS engine with configurable voices, speeds, and languages, supporting both local storage and S3 cloud integration with automatic file cleanup.
Back to servers
Setup instructions
Provider
mberg
Release date
Mar 24, 2025
Language
Python
Stats
43 stars
View on GitHub

The Kokoro Text to Speech MCP server converts text to speech and generates MP3 files with an option to upload them to Amazon S3. It uses the Kokoro TTS model from Hugging Face to create natural-sounding audio in various voices and languages.

Installation and Setup

Prerequisites

  • FFmpeg (required for MP3 conversion)

    For macOS:

    brew install ffmpeg

Basic Setup

  1. Clone the repository to your local machine
  2. Download the required model files:
  3. Place both files in the same repository directory

Configuration

Create a .env file based on the provided env.example template with your own values:

AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_S3_BUCKET_NAME=your_bucket_name
AWS_S3_REGION=us-east-1
AWS_S3_FOLDER=mp3
S3_ENABLED=true
MP3_FOLDER=/path/to/mp3/storage

MCP Configuration

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

Running the Server

The preferred method is to use UV:

uv run mcp-tts.py

Using the TTS Client

Basic Usage

Convert text to speech with default settings:

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

Reading Text from a File

Process the contents of a text file:

python mcp_client.py --file my_text.txt

Customizing Voice and Speed

Change the voice and adjust the speech speed:

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

Disabling S3 Upload for a Single Request

Generate MP3 locally only:

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

View All Options

See all available command-line options:

python mcp_client.py --help

Configuration Options

Connection Settings

  • Server: Binds to 0.0.0.0 (all interfaces) or 127.0.0.1 (localhost only)
  • Client: Connects to localhost or 127.0.0.1 when running on the same machine

Environment Variables

  • AWS Configuration:

    • AWS_ACCESS_KEY_ID: Your AWS access key
    • AWS_SECRET_ACCESS_KEY: Your AWS secret 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

  • Server Settings:

    • 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 (default: localhost)
    • DEBUG: Enable debug mode (set to "true" or "1")

  • TTS Settings:

    • TTS_VOICE: Default voice (default: af_heart)
    • TTS_SPEED: Default speech speed (default: 1.0)
    • TTS_LANGUAGE: Default language (default: en-us)

  • File Management:

    • S3_ENABLED: Enable S3 uploads (set to "true" or "1")
    • MP3_FOLDER: Path to store MP3 files
    • MP3_RETENTION_DAYS: Days to keep MP3 files before automatic deletion
    • DELETE_LOCAL_AFTER_S3_UPLOAD: Delete local files after successful S3 upload

MP3 File Management

Local Storage

  • Set MP3_FOLDER to specify where MP3 files are stored locally
  • Files remain in this folder unless deleted automatically

Automatic Cleanup

  • Configure MP3_RETENTION_DAYS=30 to automatically delete files older than 30 days
  • Enable DELETE_LOCAL_AFTER_S3_UPLOAD=true to remove local files after S3 upload

S3 Integration

  • Enable/disable S3 uploads globally with S3_ENABLED=true or S3_ENABLED=false
  • Configure AWS credentials and bucket settings in the .env file

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-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"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "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"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "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"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later