kokoro

Kokoro MCP SERVER provides an MCP (Model Context Protocol) integration for the Kokoro-82M based TTS toolkit. This server enables voice generation requests to be issued from external MCP-enabled tools (such as Claude Desktop, Cursor, or other AI agents) without leaving your editor or UI. The MCP server runs the core TTS engine, handles context management, and returns generated audio aligned to the requested text chunks. You can use the MCP flow to generate voiceovers inline within your AI-assisted workflows or batch processes. The server exposes an endpoint that external tools can call to request synthesis using a specified voice, text, and optional processing settings. In addition to MCP, the project also offers a CLI and a Streamlit web UI for standalone usage, making it easy to test and validate TTS outputs before integrating with MCP.

To use MCP, start the Kokoro MCP SERVER, then issue generate requests from your MCP-enabled editor or agent. For Claude Desktop or Cursor, you can trigger an in-context voice generation like: “Generate voiceover for this section using am_michael voice.” The server will return the generated audio data or a path to the saved audio file depending on your integration. The system supports batch processing, script processing, and multiple voices, enabling teams to standardize voice assets across tools. If you also enable the optional Streamlit UI, you can visually configure voices, processing options, and monitor analytics while developing MCP integrations.

Prerequisites:

• Python 3.10+ installed on the host
• Git (optional, for cloning)
• System dependencies for TTS: espeak-ng, ffmpeg, and related audio libraries as documented (Ubuntu/Debian/macOS/Windows guidance in README)

Installation steps:

1. Set up a Python virtual environment (recommended): python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate

2. Install the package in editable mode with all features (complete set including MCP server and UI): pip install -e ".[complete]"

3. Optional: install only MCP-related components if you plan to use MCP without the Streamlit UI: pip install -e ".[mcp,cli]"

4. (Optional) Install Streamlit UI if you want the web interface: pip install -e ".[streamlit]"

5. Run the MCP server (example): python -m aparsoft_tts.mcp_server

6. Run the Streamlit UI (optional): python run_streamlit.py

Prerequisites checklist:

• Ensure espeak-ng, ffmpeg, and libsndfile1 are installed on the system prior to running TTS operations.
• If you use the Steamlit UI, ensure you have Streamlit installed (pip install streamlit).

For a full, detailed setup and troubleshooting, refer to INSTALLATION.md in the project.

Tips and notes:

• The MCP server is designed to work with Claude Desktop and Cursor; you can trigger generation directly from within those editors without leaving your workspace.
• Environment variables like MCP_HOST and MCP_PORT help you tailor network exposure and binding. Consider using a private network or containerized deployment for production.
• When running in Docker or containerized environments, ensure port mappings (e.g., -p 5000:5000) align with your MCP client configuration.
• Logs are structured JSON by default to support log aggregation and tracing; adjust LOG_LEVEL to INFO, DEBUG, or ERROR as needed.
• If you encounter audio quality issues, verify that the system dependencies (espeak-ng, ffmpeg, librosa) are correctly installed and that the Kokoro-82M model files are accessible.
• The mcp_config example provided assumes a Python-based MCP server entry point at aparsoft_tts.mcp_server; adjust the module path if your package structure differs.