CHeema-Text-to-Voice-MCP-Server

Servidor MCP Cheema Text-to-Voice

Cheema Text-to-Voice es un servidor MCP gratuito y de código abierto que le da una voz real a cualquier asistente de IA compatible con MCP, incluidos Claude Desktop, Claude Code y n8n. Ejecuta los modelos de texto a voz NeuTTS localmente en tu propia CPU o GPU, por lo que no hay claves API que configurar, ningún servicio en la nube en el proceso y sin facturación por carácter: el texto entra, un archivo WAV sale, todo en tu máquina. Pídele a tu asistente que hable y sintetizará voz natural en cinco voces integradas en cuatro idiomas, o clonará una nueva voz a partir de una grabación corta en segundos.

---

Enlaces

• Directorio MCP: listado en mcpservers.org
• Caso de estudio: cómo se construyó Cheema Text-to-Voice

Creado por Tayyab Ilyas, Ingeniero de Agentes de IA en Barcelona.

---

¿Qué Puede Hacer?

Solo pídele a tu asistente de IA que hable, y él se encarga del resto:

"Di hola en francés usando la voz juliette"

"Convierte este párrafo a voz y guárdalo como intro.wav"

"Clona mi voz a partir de esta grabación y úsala para leer mi ensayo"

Características:

• 5 voces integradas en 4 idiomas: inglés (jo, dave), alemán (greta), francés (juliette), español (mateo)
• Clonación de voz instantánea a partir de una muestra WAV de 3 a 15 segundos, persistente entre reinicios
• 5 herramientas MCP (tts_help, tts_list_speakers, tts_list_models, tts_synthesize, tts_add_speaker) más 2 plantillas de prompt listas para usar
• 3 transportes: stdio para Claude Desktop y Claude Code, SSE y Streamable HTTP para n8n y otros clientes remotos
• Modelos base NeuTTS intercambiables, incluidas variantes GGUF cuantizadas más pequeñas, con aceleración CUDA opcional
• 100% local: sin claves API, sin llamadas a la nube, sin facturación por carácter

---

Inicio Rápido

1. Instalar Requisitos Previos

Necesitas Python 3.10+ y espeak-ng:

# Ubuntu / Debian
sudo apt install espeak-ng

# macOS
brew install espeak-ng

# Windows
choco install espeak-ng

2. Clonar e Instalar

git clone https://github.com/MuhammadTayyabIlyas/CHeema-Text-to-Voice-MCP-Server.git
cd CHeema-Text-to-Voice-MCP-Server

python -m venv venv
source venv/bin/activate        # Linux/macOS
# venv\Scripts\activate          # Windows

pip install -e .
pip install "mcp[cli]"

3. Conectar a Tu Asistente de IA

Elige tu plataforma y sigue los pasos a continuación.

---

Configuración por Plataforma

Claude Desktop

Añade esto a tu archivo de configuración:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cheema-tts": {
      "command": "/full/path/to/CHeema-Text-to-Voice-MCP-Server/venv/bin/python",
      "args": ["/full/path/to/CHeema-Text-to-Voice-MCP-Server/mcp_server.py"],
      "env": {}
    }
  }
}

Reinicia Claude Desktop. Verás las herramientas TTS aparecer en el menú de herramientas.

Claude Code

claude mcp add cheema-tts -- /full/path/to/venv/bin/python /full/path/to/mcp_server.py

Luego solo pídele a Claude que genere voz en cualquier conversación.

n8n

Inicia el servidor en modo SSE:

cd CHeema-Text-to-Voice-MCP-Server
source venv/bin/activate
python mcp_server.py --transport sse --host 127.0.0.1 --port 8000

En tu flujo de trabajo de n8n:

1. Añade un nodo AI Agent con una MCP Client Tool
2. Configura el tipo de conexión como SSE
3. Ingresa la URL: http://127.0.0.1:8000/sse
4. El agente ahora puede llamar a cualquier herramienta TTS

Cualquier Otro Cliente MCP

Inicia el servidor con tu transporte preferido:

# SSE (for web platforms and remote clients)
python mcp_server.py --transport sse --host 0.0.0.0 --port 8000

# Streamable HTTP
python mcp_server.py --transport streamable-http --host 0.0.0.0 --port 8000

Conecta tu cliente MCP a:

• SSE: http://<your-host>:8000/sse
• HTTP: http://<your-host>:8000/mcp

---

Voces Disponibles

Voz	Idioma	Descripción
jo	Inglés	Predeterminada: voz femenina clara y natural
dave	Inglés	Voz masculina
greta	Alemán	Voz femenina alemana
juliette	Francés	Voz femenina francesa
mateo	Español	Voz masculina española

Usa tts_list_speakers para ver todas las voces, incluidas las personalizadas que hayas añadido.

---

Clonación de Voz

Clona cualquier voz a partir de una muestra de audio corta:

1. Graba o encuentra un archivo WAV: de 3 a 15 segundos de voz limpia
2. Conoce la transcripción: las palabras exactas pronunciadas en la grabación
3. Pídele a tu asistente de IA:

"Añade un nuevo hablante llamado 'alex' desde /path/to/recording.wav, con la transcripción 'Esto es lo que dije en la grabación'"

O llama a la herramienta directamente:

tts_add_speaker(name="alex", wav_path="/path/to/recording.wav", ref_text="This is what I said in the recording")

Las voces personalizadas se guardan permanentemente y están disponibles entre reinicios.

Consejos para mejores resultados:

• Audio mono, frecuencia de muestreo de 16-44 kHz
• De 3 a 15 segundos de voz continua y natural
• Ruido de fondo mínimo

---

Herramientas Disponibles

Herramienta	Qué Hace
tts_help	Muestra una guía de uso completa con ejemplos (empieza aquí)
tts_synthesize	Convierte texto a voz, guarda un archivo WAV
tts_list_speakers	Lista todas las voces disponibles
tts_list_models	Muestra el modelo activo y las alternativas
tts_add_speaker	Clona una nueva voz a partir de una muestra de audio

Parámetros de tts_synthesize

Parámetro	Requerido	Predeterminado	Descripción
text	Sí	ninguno	El texto a convertir en voz
speaker	No	"jo"	Qué voz usar
output_filename	No	generado automáticamente	Nombre de archivo personalizado para la salida WAV

Prompts MCP (Plantillas)

Prompt	Descripción
quick_speech	Generación de voz rápida: solo proporciona texto y hablante opcional
voice_clone_guide	Guía paso a paso para añadir una nueva voz

Estas aparecen automáticamente en el selector de prompts de Claude Desktop.

---

Modelos

El modelo predeterminado (neutts-nano) funciona muy bien en CPU. Los modelos más grandes producen mayor calidad pero necesitan más recursos.

Modelo	Idioma	Tamaño	Notas
neuphonic/neutts-nano	Inglés	~229M	Predeterminado: rápido, buena calidad
neuphonic/neutts-air	Inglés	~552M	Mayor calidad, más lento
neuphonic/neutts-nano-german	Alemán	~229M	Idioma alemán
neuphonic/neutts-nano-french	Francés	~229M	Idioma francés
neuphonic/neutts-nano-spanish	Español	~229M	Idioma español
neuphonic/neutts-*-q4-gguf	varía	más pequeño	Cuantizado: más rápido, menos memoria
neuphonic/neutts-*-q8-gguf	varía	mediano	Cuantizado: equilibrado

Cambia los modelos usando variables de entorno:

NEUTTS_BACKBONE="neuphonic/neutts-air" python mcp_server.py

---

Configuración

Todos los ajustes son opcionales. Los valores predeterminados funcionan de inmediato.

Variable	Predeterminado	Descripción
NEUTTS_BACKBONE	neuphonic/neutts-nano	Repositorio de modelos HuggingFace
NEUTTS_BACKBONE_DEVICE	cpu	cpu o cuda para GPU
NEUTTS_CODEC	neuphonic/neucodec	Modelo de códec de audio
NEUTTS_CODEC_DEVICE	cpu	cpu o cuda para GPU
NEUTTS_OUTPUT_DIR	./output	Dónde se guardan los archivos WAV
NEUTTS_SAMPLES_DIR	./samples	Muestras de hablante integradas
NEUTTS_SPEAKERS_DIR	./speakers	Datos de voz personalizados
NEUTTS_TRANSPORT	stdio	stdio, sse o streamable-http
NEUTTS_HOST	127.0.0.1	Dirección de enlace (solo SSE/HTTP)
NEUTTS_PORT	8000	Puerto de enlace (solo SSE/HTTP)

Aceleración GPU

Para una síntesis más rápida en GPUs NVIDIA:

NEUTTS_BACKBONE_DEVICE=cuda NEUTTS_CODEC_DEVICE=cuda python mcp_server.py

Requiere PyTorch con soporte CUDA.

---

Ejecución como Servicio

Para uso en producción, crea un servicio systemd para que se inicie automáticamente:

# /etc/systemd/system/cheema-tts.service
[Unit]
Description=Cheema Text-to-Voice MCP Server
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/CHeema-Text-to-Voice-MCP-Server
ExecStart=/path/to/venv/bin/python mcp_server.py --transport sse --host 127.0.0.1 --port 8000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now cheema-tts

Para exponerlo a través de HTTPS, coloca un proxy inverso Nginx o Caddy al frente con estos ajustes clave para SSE:

• Deshabilitar el buffering del proxy (proxy_buffering off)
• Configurar un tiempo de espera de lectura largo (proxy_read_timeout 86400)
• Añadir el encabezado X-Accel-Buffering: no

---

Solución de Problemas

¿El servidor no arranca?

• Verifica espeak-ng: espeak-ng --version
• Verifica las dependencias: pip list | grep -E "mcp|neutts|torch|soundfile"

¿Sin salida de audio?

• Revisa el directorio output/ para archivos WAV
• Verifica el nombre del hablante con tts_list_speakers

¿Primera ejecución lenta?

• Normal: la primera ejecución descarga los pesos del modelo desde HuggingFace (~200-500MB). Se almacenan en caché después.

¿Quieres aceleración GPU?

• Configura NEUTTS_BACKBONE_DEVICE=cuda y NEUTTS_CODEC_DEVICE=cuda

---

Cómo Funciona

1. El servidor carga el modelo base NeuTTS y el códec de audio al inicio
2. Las huellas de voz del hablante (archivos .pt) se cargan en memoria
3. Cuando solicitas voz, el texto se fonemiza y se combina con la referencia de voz del hablante
4. El modelo genera tokens de voz, decodificados en una forma de onda de 24kHz
5. La salida se guarda como un archivo WAV estándar

---

Estructura del Proyecto

CHeema-Text-to-Voice-MCP-Server/
├── mcp_server.py       # MCP server entry point
├── neutts/             # NeuTTS engine
├── samples/            # Built-in speaker voices (.wav, .pt, .txt)
├── speakers/           # Custom cloned voices (auto-created)
├── output/             # Generated audio files (auto-created)
└── examples/           # Usage examples

---

Créditos

• NeuTTS por Neuphonic, el motor TTS
• Protocolo MCP por Anthropic, el estándar de herramientas de IA

---

Autor

Tayyab Ilyas, Investigador de Doctorado y Fundador de EdTech

Construyendo herramientas impulsadas por IA para educadores e investigadores.

---

Licencia

Licencia MIT. Los modelos NeuTTS subyacentes tienen sus propias licencias. Consulta el repositorio de NeuTTS para más detalles.

---

Servidor MCP Cheema Text-to-Voice
Dale una voz a tu asistente de IA.