Kokoro Speech

🚀 Speech MCP Server

A Model Context Protocol (MCP) server that provides text-to-speech functionality, utilizing the Kokoro TTS model.

🚀 Quick Start

Configuration

The server can be configured via the following environment variables:

In Cursor:

{
  "mcpServers": {
    "speech": {
      "command": "npx",
      "args": [
        "-y",
        "speech-mcp-server"
      ],
      "env": {
        "MCP_DEFAULT_SPEECH_SPEED": 1.3,
        "MCP_DEFAULT_VOICE": "af_bella"
      }
    }
  }
}

✨ Features

• Text-to-Speech Conversion: Convert input text into natural-sounding voice output.
• Customizable Voice Tones: Support multiple voice tone selections to meet different scenario requirements.
• Automatic Model Initialization: The server will automatically download and initialize the TTS model upon startup.
• Fault Recovery Mechanism: In case of model initialization failure, the server will automatically retry up to 3 times and clean up old files before each retry.

📦 Installation

1. Install via npm:

npm install -g @decodershq/speech-mcp-server

2. Start the server:

npm start

💻 Usage Examples

Basic Usage

Configure Environment Variables

Before starting the server, you can customize its behavior by setting the following environment variables:

• MCP_DEFAULT_SPEECH_SPEED: Adjust the speed of the voice output.
• MCP_DEFAULT_VOICE: Specify the default voice tone.

Invoke Tools

1. Text-to-Speech:

echo '{"type":"request","method":"call_tool","params":{"name":"text_to_speech","arguments":{"text":"Hello world","voice":"af_bella"}}}' | node dist/index.js

2. List Available Voices:

echo '{"type":"request","method":"list_voices","params":{}}' | node dist/index.js

3. Get Model Status:

echo '{"type":"request","method":"get_model_status","params":{}}' | node dist/index.js

Advanced Usage

Integration with Claude Desktop

To use this server in Claude Desktop, add the following content to the ~/Library/Application Support/Claude/claude_desktop_config.json file:

{
  "servers": {
    "speech": {
      "command": "npx",
      "args": ["@decodershq/speech-mcp-server"]
    }
  }
}

📄 License

This project is under the MIT License. For more details, please refer to the LICENSE file.

🔧 Troubleshooting

Model Initialization Issues

If you encounter problems with model initialization:

1. The server will automatically clean up old files before each retry.
2. Use the get_model_status tool to monitor the initialization progress and error messages.
3. If all retries fail, you can manually delete the model files:

# Delete model files (MacOS/Linux)
rm -rf ~/.npm/_npx/**/node_modules/@huggingface/transformers/.cache/onnx-community/Kokoro-82M-v1.0-ONNX/onnx/model_quantized.onnx
rm -rf ~/.cache/huggingface/transformers/onnx-community/Kokoro-82M-v1.0-ONNX/onnx/model_quantized.onnx

# Then restart the server
npm start

The response from the get_model_status tool will contain retry information:

{
  "content": [{
    "type": "text",
    "text": "Model Status: Initializing (5 seconds elapsed, Retry 1/3)"
  }]
}