Overview

Kokoro TTS MCP Server is a small service that converts text into MP3 audio using the Kokoro TTS engine and exposes that functionality as an MCP-compatible tool. The server can run locally or in a container, producing MP3 files for client consumption. For production workflows it can optionally upload generated MP3 files to Amazon S3, which enables scalable storage, CDN-backed delivery, and simple links for downstream services.

This server is useful when you need automated, programmatic text-to-speech (TTS) output that integrates with existing ML orchestration tools or microservice architectures. It provides a predictable API for generating audio, configurable audio encoding and naming, and integration points for persisting and serving audio artifacts.

Features

Generate MP3 audio from arbitrary text using Kokoro TTS
MCP-compatible tool endpoint for integration with model orchestration or agents
Optional automatic upload of generated files to Amazon S3
Configurable output format, bitrate, and filename pattern
Runs as a standalone binary or inside Docker for easy deployment
Simple HTTP/MCP examples for getting started quickly

Installation / Configuration

Requirements

A running Kokoro TTS binary or library accessible to the server (local or embedded)
Go/Rust/Node runtime is not required by clients — the server is delivered as a container or binary (see repository releases)
AWS credentials if S3 upload is enabled

Example: run locally with Docker

# build (if building locally from source)
docker build -t kokoro-tts-mcp:latest .

# run container (uploads disabled)
docker run --rm -p 8080:8080 \
  -e MCP_SERVER_PORT=8080 \
  kokoro-tts-mcp:latest

Docker Compose example with S3 enabled

version: "3.8"
services:
  kokoro-tts:
    image: mberg/kokoro-tts-mcp:latest
    ports:
      - "8080:8080"
    environment:
      - MCP_SERVER_PORT=8080
      - S3_ENABLED=true
      - S3_BUCKET=my-tts-bucket
      - AWS_REGION=us-east-1
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}

Environment variables

Variable	Required	Description
MCP_SERVER_PORT	no (default: 8080)	Port the server listens on
S3_ENABLED	no (default: false)	Whether to auto-upload generated files to S3
S3_BUCKET	yes if S3_ENABLED	Target S3 bucket name
AWS_REGION	yes if S3_ENABLED	AWS region for S3
AWS_ACCESS_KEY_ID	yes if S3_ENABLED	AWS key for S3 access
AWS_SECRET_ACCESS_KEY	yes if S3_ENABLED	AWS secret for S3 access
OUTPUT_FORMAT	no (default: mp3)	Audio output format (mp3 by default)
BITRATE	no (default: 128k)	MP3 bitrate

Configuration file example (JSON)

{
  "server": {
    "port": 8080,
    "output_format": "mp3",
    "bitrate": "128k"
  },
  "s3": {
    "enabled": true,
    "bucket": "my-tts-bucket",
    "region": "us-east-1",
    "prefix": "audio/"
  }
}

Available Tools / Resources

The server exposes a minimal set of capabilities intended for easy integration:

tts.generate (MCP tool) — Input: text (string), filename (optional), voice/options (optional). Output: local path or S3 URL to generated MP3.
HTTP endpoint — A simple POST endpoint for environments that do not speak MCP: POST /generate with JSON body { “text”: “…”, “filename”: “…”, “voice”: “…” }.

Example HTTP request (curl)

curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello world from Kokoro TTS","filename":"hello-world.mp3"}'

Example success response (JSON)

{
  "filename": "hello-world.mp3",
  "path": "/tmp/tts/hello-world.mp3",
  "s3_url": "https://my-tts-bucket.s3.amazonaws.com/audio/hello-world.mp3"
}

Use Cases

Automated voice notifications
- Convert alert messages or system notifications into MP3 files and host them on S3 for playback by other services or devices.
Podcast or audiobook generation
- Batch-process chapters or articles into MP3 files. Use S3 storage and a CDN for scalable distribution.
Multimodal agent responses
- Agents that implement MCP can call the tts.generate tool to synthesize spoken responses and provide URLs to clients.
Accessibility enhancements
- Dynamically generate audio versions of articles, documentation, or UI text and serve them from a shared storage bucket.

Best Practices and Notes

Secure AWS credentials using environment variables, IAM roles, or secrets management; avoid hardcoding keys.
When enabling S3 uploads, configure a lifecycle policy or storage class to manage costs for large volumes of generated audio.
For high-throughput workloads, run the server behind a load balancer and use concurrency controls on the TTS engine to avoid resource contention.
Validate input length and sanitize text to avoid injection or unexpected behaviors in synthesized output.

For full implementation details, API reference, and examples, see the repository at https://github.com/mberg/kokoro-tts-mcp.

Kokoro TTS MCP Server: Text-to-MP3 with S3 Upload