Kokoro Tts MCP

1<a href="https://glama.ai/mcp/servers/@mberg/kokoro-tts-mcp">
2  <img width="380" height="200" src="https://glama.ai/mcp/servers/@mberg/kokoro-tts-mcp/badge" alt="Kokoro Text to Speech Server MCP server" />
3</a>
4 
5## Kokoro Text to Speech (TTS) MCP Server
6 
7Kokoro Text to Speech MCP server that generates .mp3 files with option to upload to S3.
8 
9Uses: https://huggingface.co/spaces/hexgrad/Kokoro-TTS
10 
11## Configuration
12 
13* Clone to a local repo.
14* Download the [Kokoro Onnx Weights](https://github.com/thewh1teagle/kokoro-onnx) for [kokoro-v1.0.onnx](https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/kokoro-v1.0.onnx) and [voices-v1.0.bin](https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/voices-v1.0.bin) and store in the same repo.
15 
16Add the following to your MCP configs. Update with your own values.
17 
18```
19  "kokoro-tts-mcp": {
20      "command": "uv",
21      "args": [
22        "--directory",
23        "/path/toyourlocal/kokoro-tts-mcp",
24        "run",
25        "mcp-tts.py"
26      ],
27      "env": {
28        "TTS_VOICE": "af_heart",
29        "TTS_SPEED": "1.0",
30        "TTS_LANGUAGE": "en-us",
31        "AWS_ACCESS_KEY_ID": "",
32        "AWS_SECRET_ACCESS_KEY": "",
33        "AWS_REGION": "us-east-1",
34        "AWS_S3_FOLDER": "mp3",
35        "S3_ENABLED": "true",
36        "MP3_FOLDER": "/path/to/mp3"
37      } 
38    }
39```
40 
41### Install ffmmeg
42 
43This is needed to convert .wav to .mp3 files
44 
45For mac:
46 
47``` 
48brew install ffmpeg
49```
50 
51To run locally add these to your .env file.  See env.example and copy to .env and modify with your own values.
52 
53### Supported Environment Variables
54 
55- `AWS_ACCESS_KEY_ID`: Your AWS access key ID
56- `AWS_SECRET_ACCESS_KEY`: Your AWS secret access key
57- `AWS_S3_BUCKET_NAME`: S3 bucket name
58- `AWS_S3_REGION`: S3 region (e.g., us-east-1)
59- `AWS_S3_FOLDER`: Folder path within the S3 bucket
60- `AWS_S3_ENDPOINT_URL`: Optional custom endpoint URL for S3-compatible storage
61- `MCP_HOST`: Host to bind the server to (default: 0.0.0.0)
62- `MCP_PORT`: Port to listen on (default: 9876)
63- `MCP_CLIENT_HOST`: Hostname for client connections to the server (default: localhost)
64- `DEBUG`: Enable debug mode (set to "true" or "1")
65- `S3_ENABLED`: Enable S3 uploads (set to "true" or "1")
66- `MP3_FOLDER`: Path to store MP3 files (default is 'mp3' folder in script directory)
67- `MP3_RETENTION_DAYS`: Number of days to keep MP3 files before automatic deletion
68- `DELETE_LOCAL_AFTER_S3_UPLOAD`: Whether to delete local MP3 files after successful S3 upload (set to "true" or "1")
69- `TTS_VOICE`: Default voice for the TTS client (default: af_heart)
70- `TTS_SPEED`: Default speed for the TTS client (default: 1.0)
71- `TTS_LANGUAGE`: Default language for the TTS client (default: en-us)
72 
73## Running the Server Locally
74 
75Preferred method use UV 
76```
77uv run mcp-tts.py
78```
79 
80 
81## Using the TTS Client
82 
83The `mcp_client.py` script allows you to send TTS requests to the server. It can be used as follows:
84 
85### Connection Settings
86 
87When running the server and client on the same machine:
88- Server should bind to `0.0.0.0` (all interfaces) or `127.0.0.1` (localhost only)
89- Client should connect to `localhost` or `127.0.0.1`
90 
91 
92### Basic Usage
93 
94```bash
95python mcp_client.py --text "Hello, world!"
96```
97 
98### Reading Text from a File
99 
100```bash
101python mcp_client.py --file my_text.txt
102```
103 
104### Customizing Voice and Speed
105 
106```bash
107python mcp_client.py --text "Hello, world!" --voice "en_female" --speed 1.2
108```
109 
110### Disabling S3 Upload
111 
112```bash
113python mcp_client.py --text "Hello, world!" --no-s3
114```
115 
116### Command-line Options
117 
118```bash
119python mcp_client.py --help
120```
121 
122## MP3 File Management
123 
124The TTS server generates MP3 files that are stored locally and optionally uploaded to S3. You can configure how these files are managed:
125 
126### Local Storage
127 
128- Set `MP3_FOLDER` in your `.env` file to specify where MP3 files are stored
129- Files are kept in this folder unless automatically deleted
130 
131### Automatic Cleanup
132 
133- Set `MP3_RETENTION_DAYS=30` (or any number) to automatically delete files older than that number of days
134- Set `DELETE_LOCAL_AFTER_S3_UPLOAD=true` to delete local files immediately after successful S3 upload
135 
136### S3 Integration
137 
138- Enable/disable S3 uploads with `S3_ENABLED=true` or `DISABLE_S3=true`
139- Configure AWS credentials and bucket settings in the `.env` file
140- S3 uploads can be disabled per-request using the client's `--no-s3` option
141