Advanced TTS MCP Server

Advanced TTS MCP Server

Un servidor MCP de texto a voz (TTS) de alta calidad y rico en funciones, con implementación nativa en TypeScript. Diseñado para aplicaciones profesionales que requieren síntesis de voz natural y expresiva con controles avanzados y cero dependencias externas.

✨ Características

🎯 Control de Voz Avanzado

• 10 Voces de Alta Calidad - Voces masculinas y femeninas con personalidades distintivas
• Control de Emociones - Neutral, feliz, emocionado, tranquilo, serio, casual, seguro
• Ritmo Dinámico - Modos natural, conversacional, presentación, tutorial, narrativo
• Velocidad y Volumen - Control preciso de 0.25x a 3.0x de velocidad, 0.1x a 2.0x de volumen

🚀 Capacidades Profesionales

• Audio en Streaming - Síntesis y reproducción en tiempo real
• Procesamiento por Lotes - Maneja múltiples segmentos de texto de manera eficiente
• Múltiples Formatos - Soporte de salida WAV, MP3, FLAC, OGG
• Mejora Natural del Habla - Inserción automática de pausas y marcadores de emoción
• Gestión de Colas - Maneja múltiples solicitudes concurrentes

🔧 Integración MCP

• 6 Herramientas Potentes - Síntesis completa, procesamiento por lotes, gestión de voces
• 2 Recursos Ricos - Capacidades de voz y ejemplos de uso
• Estado en Tiempo Real - Seguimiento del progreso de procesamiento y gestión de solicitudes
• Gestión de Archivos - Guardar, listar y organizar salidas de audio

🚀 Inicio Rápido

Opción 1: Desplegar en Smithery.ai (Recomendado)

🎯 Despliegue con un clic en la plataforma Smithery

1. Desplegar ahora: Visita Smithery.ai e importa este repositorio
2. Configurar: Establece tu voz y configuración de habla preferidas
3. Usar al instante: Accede mediante Claude Desktop o cualquier cliente compatible con MCP

Beneficios:

• ✅ Cero configuración requerida
• ✅ Escalado y actualizaciones automáticas
• ✅ No se necesitan descargas de modelos
• ✅ Alojamiento de nivel empresarial

📋 Guía completa de despliegue en Smithery →

Opción 2: Instalación Local

Requisitos previos:

• Node.js 18+

Instalación:

1. Clona el repositorio

git clone https://github.com/samihalawa/advanced-tts-mcp.git
cd advanced-tts-mcp

2. Instala las dependencias

npm install

3. Configura Claude Desktop

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "advanced-tts": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/advanced-tts-mcp"
    }
  }
}

4. ¡Empieza a usarlo!

# Build TypeScript
npm run build

# Start server
npm start

Reinicia Claude Desktop y comienza a sintetizar con voces naturales y expresivas.

🎙️ Voces Disponibles

ID de Voz	Nombre	Género	Descripción
af_heart	Heart	Femenino	Voz cálida y amigable (predeterminada)
af_sky	Sky	Femenino	Voz clara y brillante
af_bella	Bella	Femenino	Voz elegante y sofisticada
af_sarah	Sarah	Femenino	Voz profesional y segura
af_nicole	Nicole	Femenino	Voz suave y relajante
am_adam	Adam	Masculino	Voz fuerte y autoritaria
am_michael	Michael	Masculino	Voz amigable y accesible
bf_emma	Emma	Femenino	Voz joven y enérgica
bf_isabella	Isabella	Femenino	Voz madura y expresiva
bm_lewis	Lewis	Masculino	Voz profunda y resonante

📚 Ejemplos de Uso

Síntesis Básica

# Simple text-to-speech
await synthesize_speech(
    text="Hello! Welcome to Advanced TTS.",
    voice_id="af_heart"
)

Expresión Emocional

# Excited announcement
await synthesize_speech(
    text="This is amazing news! You're going to love this new feature!",
    voice_id="af_heart",
    emotion="excited",
    pacing="conversational",
    speed=1.1
)

Presentación Profesional

# Tutorial narration
await synthesize_speech(
    text="Step one: Open your browser. Step two: Navigate to the website.",
    voice_id="am_adam", 
    emotion="calm",
    pacing="tutorial",
    speed=0.9
)

Procesamiento por Lotes

# Multiple segments with pauses
await batch_synthesize(
    segments=[
        "Welcome to our presentation.",
        "Today we'll cover three main topics.", 
        "Let's begin with the first topic."
    ],
    voice_id="af_sarah",
    emotion="confident",
    pacing="presentation",
    merge_output=True,
    segment_pause=1.0,
    save_file=True
)

🛠️ Herramientas Disponibles

synthesize_speech

Convierte texto en voz natural con control total sobre las características de la voz.

Parámetros:

• text - Texto a sintetizar (máx. 10,000 caracteres)
• voice_id - Selección de voz (ver tabla anterior)
• speed - Velocidad del habla (0.25-3.0)
• emotion - Emoción de la voz (neutral, feliz, emocionado, tranquilo, serio, casual, seguro)
• pacing - Estilo de habla (natural, conversacional, presentación, tutorial, narrativo, rápido, lento)
• volume - Volumen de audio (0.1-2.0)
• output_format - Formato de archivo (wav, mp3, flac, ogg)
• save_file - Guardar en archivo (booleano)
• filename - Nombre de archivo personalizado

batch_synthesize

Procesa múltiples segmentos de texto de manera eficiente con fusión opcional.

Parámetros:

• segments - Lista de segmentos de texto
• merge_output - Combinar en un solo archivo
• segment_pause - Pausa entre segmentos (0.0-5.0s)
• Todos los parámetros de síntesis anteriores

get_voices

Recupera información completa de la voz y sus capacidades.

get_status

Verifica el estado de procesamiento de las solicitudes de síntesis.

cancel_request

Cancela operaciones de síntesis activas.

list_output_files

Explora archivos de audio guardados con metadatos.

🎛️ Controles de Voz

Emociones

• Neutral - Tono estándar y profesional
• Feliz - Expresión alegre y optimista
• Emocionado - Entrega entusiasta y enérgica
• Tranquilo - Tono relajado y reconfortante
• Serio - Entrega formal y autoritaria
• Casual - Estilo relajado y conversacional
• Seguro - Tono profesional y asertivo

Estilos de Ritmo

• Natural - Ritmo equilibrado, similar al humano
• Conversacional - Ritmo de discusión casual
• Presentación - Ritmo de habla profesional
• Tutorial - Entrega educativa y clara
• Narrativo - Ritmo de narración de historias
• Rápido - Entrega rápida (1.2x velocidad base)
• Lento - Entrega deliberada (0.8x velocidad base)

🎵 Formatos de Audio

Formato	Calidad	Caso de Uso
WAV	Sin comprimir	Máxima calidad, edición
MP3	Comprimido	Web, streaming, compartir
FLAC	Sin pérdida	Archivado, almacenamiento de alta calidad
OGG	Comprimido	Alternativa de código abierto

🔧 Configuración

Variables de Entorno

# Model paths (optional)
KOKORO_MODEL_PATH=./kokoro-v1.0.onnx
KOKORO_VOICES_PATH=./voices-v1.0.bin

# Output settings
TTS_OUTPUT_DIR=./audio_output
TTS_MAX_QUEUE_SIZE=100

# Audio settings  
TTS_DEFAULT_VOICE=af_heart
TTS_ENABLE_STREAMING=true

Configuración del Servidor

config = ServerConfig(
    model_path="./kokoro-v1.0.onnx",
    voices_path="./voices-v1.0.bin", 
    output_dir="./audio_output",
    max_queue_size=100,
    enable_streaming=True,
    default_voice="af_heart"
)

🏗️ Arquitectura

├── src/advanced_tts/
│   ├── __init__.py          # Package initialization
│   ├── server.py            # MCP server implementation  
│   ├── engine.py            # Kokoro TTS engine wrapper
│   ├── models.py            # Data models and validation
│   └── utils.py             # Utility functions
├── pyproject.toml           # Project configuration
├── README.md               # Documentation
└── LICENSE                 # MIT License

🤝 Contribuciones

¡Contribuciones bienvenidas! Áreas de mejora:

• Modelos de voz adicionales
• Síntesis de streaming en tiempo real
• Efectos de audio avanzados
• Soporte multilingüe
• Optimizaciones de rendimiento

📄 Licencia

Licencia MIT - consulta LICENSE para más detalles.

🙏 Agradecimientos

• Kokoro TTS - Síntesis de voz neuronal de alta calidad
• Protocolo MCP - Integración perfecta de modelos de IA
• FastMCP - Marco de servidor eficiente

---

Desarrollado por Sami Halawa

Transforma tu texto en voz natural y expresiva con Advanced TTS MCP Server.