Speech MCP Server

Speech MCP Server

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona capacidades de texto a voz utilizando el modelo TTS Kokoro.

Configuración

El servidor se puede configurar utilizando las siguientes variables de entorno:

Variable	Descripción	Predeterminado	Rango Válido
MCP_DEFAULT_SPEECH_SPEED	Multiplicador de velocidad predeterminado para texto a voz	1.1	0.5 a 2.0
MCP_DEFAULT_VOICE	Voz predeterminada para texto a voz	af_bella	Cualquier ID de voz válido

En Cursor:

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

Características

• 🎯 Texto a voz de alta calidad utilizando el modelo TTS Kokoro
• 🗣️ Múltiples opciones de voz disponibles
• 🎛️ Parámetros de voz personalizables (voz, velocidad)
• 🔌 Interfaz compatible con MCP
• 📦 Instalación y configuración sencillas
• 🚀 No se requiere clave API

Instalación

# Using npm
npm install speech-mcp-server

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

# Using yarn
yarn add speech-mcp-server

Uso

Ejecute el servidor:

# Using default configuration
npm start

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

El servidor proporciona las siguientes herramientas MCP:

• text_to_speech: Conversión básica de texto a voz
• text_to_speech_with_options: Texto a voz con velocidad personalizable
• list_voices: Lista todas las voces disponibles
• get_model_status: Verifica el estado de inicialización del modelo TTS

Desarrollo

# Clone the repository
git clone <your-repo-url>
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

Herramientas Disponibles

1. text_to_speech

Convierte texto a voz utilizando la configuración predeterminada.

{
  "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

Convierte texto a voz con parámetros personalizables.

{
  "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

Lista todas las voces disponibles para texto a voz.

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

4. get_model_status

Verifica el estado actual de la inicialización del modelo TTS. Esto es particularmente útil al iniciar el servidor por primera vez, ya que el modelo debe descargarse e inicializarse.

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

Ejemplo de respuesta:

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

Posibles valores de estado:

• uninitialized: La inicialización del modelo no ha comenzado
• initializing: El modelo se está descargando e inicializando
• ready: El modelo está listo para usar
• error: Ocurrió un error durante la inicialización

Pruebas

Puede probar el servidor utilizando el Inspector MCP o enviando mensajes JSON sin procesar:

# 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

Integración con Claude Desktop

Para usar este servidor con Claude Desktop, agregue lo siguiente a su archivo de configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Contribuciones

¡Las contribuciones son bienvenidas! No dude en enviar una Solicitud de Extracción (Pull Request).

Licencia

Licencia MIT - consulte el archivo LICENCIA para obtener más detalles.

Solución de Problemas

Problemas de Inicialización del Modelo

El servidor intenta automáticamente descargar e inicializar el modelo TTS al iniciar. Si encuentra errores de inicialización:

1. El servidor reintentará automáticamente hasta 3 veces con una limpieza entre intentos
2. Use la herramienta get_model_status para monitorear el progreso de inicialización y cualquier error
3. Si la inicialización falla después de todos los reintentos, intente eliminar manualmente los archivos del modelo:

# 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

La herramienta get_model_status ahora incluirá información de reintentos en su respuesta:

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