Skip to main content
Glama
enesjakozh
mberg

Kokoro Text to Speech MCP Server

by mberg
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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

Related MCP server: MCP Voice Soundboard

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

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

Available Tools

1 tool
text_to_speechB
    Convert text to speech using the Kokoro TTS service.
    
    Args:
        text: The text to convert to speech
        voice: Voice ID to use (default: af_heart)
        speed: Speech speed (default: 1.0)
        lang: Language code (default: en-us)
        filename: Optional filename for the MP3 (default: auto-generated UUID)
        upload_to_s3: Whether to upload to S3 if enabled (default: True)
        
    Returns:
        A dictionary with information about the generated audio file
ParametersJSON Schema
NameRequiredDescriptionDefault
textYes
voiceNoen_sarah
speedNo
langNoen-us
filenameNo
upload_to_s3No

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the output is an MP3 file and that upload to S3 is optional, which adds some context. However, it doesn't cover important aspects like rate limits, authentication requirements, error conditions, or what the returned dictionary contains. For a tool with 6 parameters and no annotation coverage, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and appropriately sized. It starts with the core purpose, then lists parameters with clear explanations, and ends with return information. Every sentence earns its place, though the formatting with 'Args:' and 'Returns:' sections is slightly verbose but still efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, no annotations, no output schema), the description is moderately complete. It excels at parameter documentation but lacks behavioral context and usage guidelines. The absence of an output schema means the description should ideally explain the return dictionary structure, which it doesn't. It's adequate but has clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description provides excellent parameter semantics beyond the input schema. With 0% schema description coverage, the description fully compensates by explaining each parameter's purpose, default values, and optionality. It clarifies that 'filename' is auto-generated if not provided and that 'upload_to_s3' depends on whether S3 is enabled. This adds significant value over the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Convert text to speech using the Kokoro TTS service.' It specifies the verb ('convert') and resource ('text to speech'), and mentions the specific service. However, without sibling tools, it cannot demonstrate differentiation from alternatives, so it doesn't reach the highest score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, constraints, or typical use cases. The only contextual information is the service name (Kokoro TTS), but this doesn't help an agent decide when this tool is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.0.0
    • Changedtext_to_speech2 fields changed
      • changedInput schema / properties / speed / default
        Previous value: -1New value: +1.2
      • changedInput schema / properties / voice / default
        Previous value: -"af_heart"New value: +"en_sarah"
  2. 1 tool update
    • First observedtext_to_speech
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of ambiguity or overlap between tools. The single tool has a clearly defined purpose of converting text to speech, which cannot be confused with any other functionality.

Naming Consistency5/5

The single tool name 'text_to_speech' follows a clear verb_noun pattern and uses snake_case consistently. With only one tool, naming consistency is inherently perfect as there are no other tools to compare against.

Tool Count2/5

A single tool is too few for a server's apparent scope of text-to-speech functionality. While the tool itself is well-defined, a complete TTS service would typically include additional tools such as listing available voices, managing audio files, or configuring settings, making this server feel thin and incomplete.

Completeness2/5

The server is severely incomplete for a text-to-speech domain. It lacks essential operations such as listing available voices, checking service status, managing generated audio files (beyond the single generation tool), or handling configuration. This creates significant gaps that will limit agent workflows and cause failures in more complex tasks.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches