Text to Speech

Servidor MCP de Texto a Voz

Dale una voz a tu asistente de IA — localmente, sin clave de API, sin cuenta y sin servicio en la nube.

Texto a Voz es un servidor de Protocolo de Contexto de Modelo (MCP) de código abierto que permite a los asistentes de IA leer texto en voz alta en la computadora del usuario. Utiliza el sintetizador de voz ya presente en el sistema operativo anfitrión, por lo que nada de lo que le pidas decir sale jamás de tu máquina.

Funciona en Windows, macOS y Linux. La instalación es una sola línea:

uvx text-to-speech-mcp

El servidor expone una herramienta controlada por modelo:

speak_text(text: string)

Úsala para texto proporcionado por el usuario, respuestas del asistente, flujos de trabajo de accesibilidad o actualizaciones de progreso habladas mientras un agente trabaja.

Por qué este

La mayoría de los servidores MCP de texto a voz envuelven una API en la nube, lo que significa una cuenta, una clave, facturación por carácter y que tu texto salga de la máquina. Este usa el motor de voz que tu sistema operativo ya incluye, por lo que funciona sin conexión, no cuesta nada y mantiene el texto local — lo cual importa si trabajas en cualquier lugar donde se regule a dónde pueden ir los datos.

También incluye una habilidad de narración para agentes, para que un asistente sepa cómo narrar, no solo que puede hacerlo.

Características

• Reproducción local a través del sintetizador integrado de la plataforma por defecto: SAPI de Windows, say de macOS o espeak-ng en Linux.
• Sin API en la nube y sin clave de API para la configuración predeterminada.
• Reproducción FIFO: las solicitudes concurrentes se hablan una a la vez, en orden.
• Finalización de herramienta bloqueante: cada llamada regresa después de que su audio termina.
• Tamaños de entrada y cola limitados para prevenir el uso descontrolado de recursos.
• Los archivos WAV temporales generados se eliminan después de la reproducción por defecto.
• Transporte estándar stdio de MCP a través del SDK oficial de Python.
• Backends opcionales de Piper, Transformers MMS y HTTP local para usuarios avanzados.

El código fuente del servidor MCP es de código abierto bajo la Licencia MIT. SAPI de Windows y el comando say de macOS son componentes propietarios de sus sistemas operativos; no son motores de voz de código abierto. espeak-ng es software de código abierto con licencia separada.

Requisitos

• Python 3.10 o más reciente.
• Un cliente MCP que admita servidores MCP stdio.
• Se recomienda uv/uvx para la instalación de MCP basada en paquetes.

Por plataforma, para el valor predeterminado de configuración cero:

Plataforma	Síntesis	Reproducción	Instalación adicional
Windows 10/11	SAPI vía PowerShell	System.Media.SoundPlayer	Ninguna
macOS	say	afplay	Ninguna
Linux / otro Unix	espeak-ng o espeak	aplay, paplay, play o ffplay	espeak-ng y un reproductor

En Debian o Ubuntu eso suele ser:

sudo apt install espeak-ng alsa-utils

Establece TEXT_TO_SPEECH_BACKEND o TEXT_TO_SPEECH_PLAYER para anular cualquiera de las dos opciones. Si falta un comando requerido, el servidor informa cuál es y cómo instalarlo en lugar de fallar silenciosamente.

Instalación

Configura un cliente MCP para ejecutar el paquete publicado en PyPI:

uvx text-to-speech-mcp

Para clientes MCP que aceptan configuración de servidor basada en comandos, usa:

command = "uvx"
args = ["text-to-speech-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 300
enabled = true

Algunos clientes usan TOML, JSON o una página de configuración gráfica. Usa uvx text-to-speech-mcp como comando del servidor y reinicia el cliente después de cambiar su configuración.

Instalar desde el código fuente

git clone https://github.com/Engr-FaizanAli/text-to-speech-mcp.git
cd text-to-speech-mcp
python -m pip install .

Luego configura el cliente para ejecutar text-to-speech-mcp directamente.

Ejemplos de indicaciones

Leer texto arbitrario:

Use the Text to Speech tool to read aloud: The deployment completed successfully.

Leer la respuesta final:

Use the Text to Speech tool to read your final response aloud before displaying it.

Leer actualizaciones de progreso intermedias visibles en orden:

Use the text_to_speech MCP server's speak_text tool for spoken progress updates.

For every meaningful intermediate update that you display to me:
1. Call speak_text with the exact update text you are about to display.
2. Wait for the call to finish before producing or speaking the next update.
3. Then display the same update in text.

Also call speak_text with the exact final answer before displaying it. Never
narrate hidden reasoning, chain-of-thought, secrets, credentials, raw tool
output, terminal logs, or source code unless I explicitly ask you to read that
content aloud. Do not invoke speech calls in parallel. If the tool is
unavailable, continue normally in text and report the failure once.

La parte text_to_speech es un nombre de servidor de cliente de ejemplo. Los clientes pueden mostrar un espacio de nombres diferente mientras mantienen el nombre de herramienta speak_text.

Contrato de herramienta

Campo	Valor
Nombre de herramienta	speak_text
Entrada	text, cadena requerida, de 1 a 50,000 caracteres
Resultado	Mensaje de finalización después de que la reproducción local termina
Orden	FIFO, una reproducción activa a la vez
Límite de cola	32 solicitudes pendientes
Uso de red con un backend integrado	Ninguno

La herramienta está controlada por modelo bajo MCP. El usuario decide cuándo pedirle al modelo que la llame, y el cliente MCP puede mostrar o requerir aprobación para las llamadas de herramienta.

Privacidad

Con cualquiera de los backends integrados, el texto se pasa del cliente MCP a un proceso local de Python y luego a los componentes de voz del sistema operativo. No se envía a este proyecto, a una API externa ni a un proveedor de TTS en la nube. Los archivos WAV generados se escriben en un directorio text-to-speech-mcp dentro del directorio temporal del sistema (%TEMP% en Windows, /tmp en macOS y Linux) y se eliminan después de la reproducción a menos que se establezca TEXT_TO_SPEECH_KEEP_AUDIO=true.

El backend http es la excepción: si el texto sale de la máquina depende por completo del endpoint que configures.

No le pidas a un asistente de IA que hable secretos, credenciales, claves privadas, razonamiento oculto o salida sensible de herramientas.

Backends opcionales

El valor predeterminado no requiere configuración. TEXT_TO_SPEECH_BACKEND no está establecido y el servidor selecciona sapi, say o espeak para coincidir con la plataforma anfitriona.

Para fijar uno explícitamente, o para usar un backend que no esté integrado en el sistema operativo, establece TEXT_TO_SPEECH_BACKEND a sapi, say, espeak, piper, transformers_mms o http. Los últimos tres requieren su propio modelo local, binario, dependencias de Python o endpoint. TEXT_TO_SPEECH_FALLBACK_BACKEND nombra un segundo backend para probar si el primero falla. Consulta configuración de backend.

Habilidad de narración para agentes

Una herramienta de voz por sí sola no le dice a un asistente cuándo o cómo hablar. Si se deja improvisar, los agentes narran razonamiento oculto, omiten las partes que realmente necesitabas o leen una paráfrasis en lugar de lo que está en pantalla.

skills/project-tts-responder/SKILL.md es una política de narración lista para usar construida sobre speak_text. Cópiala en el directorio .claude/skills/ de tu proyecto:

Modo	Comportamiento
Por lotes (predeterminado)	Una reproducción al final de un turno, que cubre cada actualización visible más la respuesta final
Transmisión	Narra cada actualización a medida que aparece — bueno para demostraciones y recorridos
Leer a petición	Lee un archivo o bloque de texto nombrado textualmente

También maneja las partes que son fáciles de hacer mal:

• Las preguntas interactivas se narran antes de que se abra el selector. Una herramienta de pregunta interactiva es en sí misma la pausa, y sus opciones viven en los parámetros de la herramienta en lugar de en texto visible — por lo que cualquier regla que narre "una vez que las opciones son visibles" se activa solo después de que el usuario ya ha respondido. Esta es la forma más común en que la narración falla silenciosamente.
• Habla exactamente lo que está en pantalla, nunca una paráfrasis.
• Nunca habla razonamiento oculto, secretos, credenciales ni salida cruda de herramientas.
• Una llamada de reproducción por turno, nunca en paralelo, con comportamiento definido cuando una llamada falla.

La habilidad se aplica cuando pides audio. Para hacer que un proyecto narre cada respuesta, dilo en las instrucciones de agente de ese proyecto — por ejemplo "narra cada respuesta en modo por lotes a menos que opte por no participar".

Compatibilidad con MCP

• Transporte MCP: stdio
• Implementación de herramienta MCP: SDK oficial de Python de MCP
• Metadatos de registro: server.json usando el esquema del 2025-12-11
• Registro de paquetes: PyPI
• Marcador de propiedad del registro: comentario mcp-name de este README
• Espacio de nombres del registro: io.github.Engr-FaizanAli/text-to-speech

Licencia

MIT. Consulta LICENCIA.