MCP Tts Server

🚀 MCP Text-to-Speech Server

A versatile text-to-speech (TTS) server built on the Model Context Protocol (MCP) framework. This server provides access to multiple TTS engines through a unified interface:

• Kokoro TTS - A high-quality local TTS engine.
• OpenAI TTS - A cloud-based TTS service implemented via OpenAI's API.

🚀 Quick Start

The MCP Text-to-Speech Server offers a unified way to access multiple TTS engines. With just a few steps, you can start using this powerful service.

✨ Features

• 🌐 Unify multiple TTS engines in a single server.
• 🎧 Play real-time audio streams.
• 🔄 Support the MCP protocol for seamless integration with Claude and other LLMs.
• 🎛️ Configure voice selection (available for both engines).
• 💬 Customize voices through natural language instructions (OpenAI).
• ⚡ Adjust the playback speed (available for both engines).
• 🛑 Control playback, including stopping audio and clearing the queue.

📦 Installation

Prerequisites

• Python 3.10 or higher.
• uv package manager.
• A valid OpenAI API key (required for OpenAI TTS).

Installation Steps

1. Clone the repository using the following commands:

git clone https://github.com/your-repository.git
cd your-repository

2. Install the dependencies:

pip install -r requirements.txt

3. Configure the .env file as needed:

OPENAI_API_KEY=your_api_key_here

4. Start the server:

uv run python tts_mcp.py

Configuration Notes

• Replace your_api_key_here with your actual OpenAI API key.
• Ensure your Python environment meets the minimum version requirement (3.10+).

Integration with Claude Desktop

This server is designed to work with Claude Desktop or other applications that support the MCP protocol. No additional configuration is required.

💻 Usage Examples

Basic Usage

# Start the server using the uv runtime environment manager
uv run python tts_mcp.py

# Or use the simplified Kokoro-only version
uv run python simple_tts_mcp.py

This command starts the MCP server, making it available for connection and use.

Advanced Usage

tts_mcp.py

tts_main()

• Accepts input parameters: text (the text to be converted), voice (voice selection, default is "default").
• Supports the following command parameters:
  • --af-synthesis: Generate voice using a file.
  • --stream: Enable audio stream playback.

tts_streaming()

• Implements real-time TTS based on OpenAI, supporting multiple languages and voice styles.

Available Voices

Kokoro TTS

• Default voice: af_heart

OpenAI TTS

• Available voices: alloy, ash, ballad, coral, echo, fable, onyx, nova, sage, shimmer
• Default model: gpt-4o-mini-tts

Development and Testing

Local Debugging

fastmcp dev ./tts_mcp.py

This command starts the MCP Inspector interface, facilitating developers to test the server's functionality.

Troubleshooting

When encountering issues, refer to the following common solutions:

1. No audio output: Check your system audio configuration.
2. OpenAI TTS fails: Confirm that your API key is valid and has TTS permissions.
3. Server not found: Ensure that the MCP server is correctly registered in your MCP host.

📄 License

This project is licensed under the Apache License 2.0. Please refer to the LICENSE file for specific terms.

Contribution Guidelines

Contributions are welcome! Feel free to submit a Pull Request.