koroko-speech-mcp

View on GitHub

Speech MCP Server

1 stars JavaScriptOthers Updated Jul 22, 2025

Documentation

Speech MCP Server

A Model Context Protocol server that provides text-to-speech capabilities using the Kokoro TTS model.

Configuration

The server can be configured using the following environment variables:

Variable	Description	Default	Valid Range
`MCP_DEFAULT_SPEECH_SPEED`	Default speed multiplier for text-to-speech	1.1	0.5 to 2.0
`MCP_DEFAULT_VOICE`	Default voice for text-to-speech	af_bella	Any valid voice ID

In Cursor:

code

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

Features

🎯 High-quality text-to-speech using Kokoro TTS model
🗣️ Multiple voice options available
🎛️ Customizable speech parameters (voice, speed)
🔌 MCP-compliant interface
📦 Easy installation and setup
🚀 No API key required

Installation

bash

# Using npm
npm install speech-mcp-server

# Using pnpm (recommended)
pnpm add speech-mcp-server

# Using yarn
yarn add speech-mcp-server

Usage

Run the server:

bash

# Using default configuration
npm start

# With custom configuration
MCP_DEFAULT_SPEECH_SPEED=1.5 MCP_DEFAULT_VOICE=af_bella npm start

The server provides the following MCP tools:

`text_to_speech`: Basic text-to-speech conversion
`text_to_speech_with_options`: Text-to-speech with customizable speed
`list_voices`: List all available voices
`get_model_status`: Check the initialization status of the TTS model

Development

bash

# Clone the repository
git clone 
cd speech-mcp-server

# Install dependencies
pnpm install

# Start development server with auto-reload
pnpm dev

# Build the project
pnpm build

# Run linting
pnpm lint

# Format code
pnpm format

# Test with MCP Inspector
pnpm inspector

Available Tools

1. text_to_speech

Converts text to speech using the default settings.

json

{
  "type": "request",
  "id": "1",
  "method": "call_tool",
  "params": {
    "name": "text_to_speech",
    "arguments": {
      "text": "Hello world",
      "voice": "af_bella"  // optional
    }
  }
}

2. text_to_speech_with_options

Converts text to speech with customizable parameters.

json

{
  "type": "request",
  "id": "1",
  "method": "call_tool",
  "params": {
    "name": "text_to_speech_with_options",
    "arguments": {
      "text": "Hello world",
      "voice": "af_bella",  // optional
      "speed": 1.0,         // optional (0.5 to 2.0)
    }
  }
}

3. list_voices

Lists all available voices for text-to-speech.

json

{
  "type": "request",
  "id": "1",
  "method": "list_voices",
  "params": {}
}

4. get_model_status

Check the current status of the TTS model initialization. This is particularly useful when first starting the server, as the model needs to be downloaded and initialized.

json

{
  "type": "request",
  "id": "1",
  "method": "call_tool",
  "params": {
    "name": "get_model_status",
    "arguments": {}
  }
}

Response example:

json

{
  "content": [{
    "type": "text",
    "text": "Model status: initializing (5s elapsed)"
  }]
}

Possible status values:

`uninitialized`: Model initialization hasn't started
`initializing`: Model is being downloaded and initialized
`ready`: Model is ready to use
`error`: An error occurred during initialization

Testing

You can test the server using the MCP Inspector or by sending raw JSON messages:

bash

# List available tools
echo '{"type":"request","id":"1","method":"list_tools","params":{}}' | node dist/index.js

# List available voices
echo '{"type":"request","id":"2","method":"list_voices","params":{}}' | node dist/index.js

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

Integration with Claude Desktop

To use this server with Claude Desktop, add the following to your Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json`):

json

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see the LICENSE file for details.

Troubleshooting

Model Initialization Issues

The server automatically attempts to download and initialize the TTS model on startup. If you encounter initialization errors:

1. The server will automatically retry up to 3 times with a cleanup between attempts

2. Use the `get_model_status` tool to monitor initialization progress and any errors

3. If initialization fails after all retries, try manually removing the model files:

bash

# Remove 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 `get_model_status` tool will now include retry information in its response:

json

{
  "content": [{
    "type": "text",
    "text": "Model status: initializing (5s elapsed, retry 1/3)"
  }]
}

Frequently asked questions

What is koroko-speech-mcp?

koroko-speech-mcp is Speech MCP Server

How do I install koroko-speech-mcp?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is koroko-speech-mcp open source?

Yes — it is hosted on GitHub at https://github.com/hammeiam/koroko-speech-mcp and has 1 stars.

Related MCP tools

firecrawl-mcp-server

🔥 Official Firecrawl MCP Server - Adds powerful web scraping and search to Cursor, Claude and any other LLM clients.

7,393 JavaScript

batch-processingclaudecontent-extraction+11

deep-research

Use any LLMs (Large Language Models) for Deep Research. Support SSE API and MCP server.

4,684 JavaScript

deep-researchdeepresearchgemini+7

mcp-feedback-enhanced

Enhanced MCP server for interactive user feedback and command execution in AI-assisted development, featuring dual interface support (Web UI and Desktop Application) with intelligent environment detection and cross-platform compatibility.

3,773 JavaScript

papersgpt-for-zotero

A powerful Zotero AI and MCP plugin with ChatGPT, Gemini 3.7, Claude Fable 5, Claude Opus 5, DeepSeek V4, Grok, OpenRouter, Kimi k3, GLM 5.3, SiliconFlow, GPT-oss, Gemma 4, Qwen 3.8

2,625 JavaScript

zoteromistralclaude+17

opendia

Connect your browser to AI models. Just use Dia on Chrome, Arc or Firefox.

1,920 JavaScript

chrome-extensiondiamcp+3

wenyan-mcp

文颜 MCP Server 可以让 AI 自动将 Markdown 文章排版后发布至微信公众号。

1,310 JavaScript

mcp-serverwenyanwechat

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP