Text-to-Speech (TTS)

Un servidor de texto a voz compatible con múltiples motores como macOS say, ElevenLabs, Google Gemini y OpenAI TTS.

GitHub

Prueba este MCPPatrocinado

Documentación

mcp-tts

Servidor MCP para TTS (Texto a Voz)

¿Qué es? 🤔

Añade texto a voz a herramientas como Claude Desktop y Cursor IDE.

Registra las herramientas TTS existentes, además de voice_tts cuando voice-say está disponible en PATH:

say_tts
voice_tts (cuando esté disponible)
elevenlabs_tts
google_tts
openai_tts

`say_tts`

Utiliza el binario say de macOS para hablar el texto con las voces integradas del sistema.

`voice_tts`

Utiliza la CLI local voice-say de Voice para ejecutar Qwen3-TTS mediante MLX. Voice no requiere clave API y mantiene el texto y el audio en el Mac. El modelo se recarga en cada invocación, por lo que el inicio suele tardar varios segundos; es preferible usarlo para resúmenes y anuncios en lugar de alertas urgentes.

La herramienta se registra solo cuando voice-say se puede resolver en PATH. Los parámetros opcionales son:

voice: voz predefinida Ryan o Aiden
tier: small para síntesis más rápida de 0.6B o large para síntesis de mayor calidad de 1.7B
style: guía de entrega en texto libre
describe: diseño de voz en texto libre; fuerza el modelo de 1.7B y no se puede combinar con voice

Voice reproduce audio directamente y no admite --output-dir; con --no-play, las llamadas fallan sin iniciar voice-say.

[!ADVERTENCIA] El repositorio de Voice es actualmente privado y se publicará próximamente, por lo que el enlace requiere acceso por ahora.

`elevenlabs_tts`

Utiliza la API de texto a voz de ElevenLabs para hablar el texto con voces de IA premium.

`google_tts`

Utiliza los modelos TTS de Gemini de Google para hablar el texto con 30 voces de alta calidad. Las voces disponibles incluyen:

Achernar, Achird, Algenib, Algieba, Alnilam, Aoede, Autonoe, Callirrhoe, Charon, Despina, Enceladus, Erinome, Fenrir, Gacrux, Iapetus, Kore, Laomedeia, Leda, Orus, Puck, Pulcherrima, Rasalgethi, Sadachbia, Sadaltager, Schedar, Sulafat, Umbriel, Vindemiatrix, Zephyr, Zubenelgenubi

`openai_tts`

Utiliza la API de texto a voz de OpenAI para hablar el texto con 10 voces de sonido natural:

alloy (Cálida, conversacional, moderna)
ash (Segura, asertiva, ligeramente texturizada)
ballad (Suave, melodiosa, ligeramente lírica)
coral (Alegre, fresca, optimista)
echo (Neutral, tranquila, equilibrada)
fable (Estilo narrador, expresiva)
nova (Clara, precisa, ligeramente formal)
onyx (Profunda, autoritaria, resonante)
sage (Tranquilizadora, empática, reconfortante)
shimmer (Brillante, animada, juguetona)
verse (Versátil, expresiva)

Admite tres modelos de calidad:

gpt-4o-mini-tts - Predeterminado, calidad y velocidad optimizadas
tts-1 - Calidad estándar, generación más rápida
tts-1-hd - Audio de alta definición, calidad premium

Características adicionales:

Control de velocidad de 0.25x a 4.0x (predeterminado: 1.0x)
Instrucciones de voz personalizadas (p. ej., "Habla con un tono alegre y positivo") mediante parámetro o variable de entorno OPENAI_TTS_INSTRUCTIONS

Configuración

TTS secuencial vs. concurrente

De forma predeterminada, el servidor TTS aplica operaciones de voz secuenciales: solo una solicitud TTS puede reproducir audio a la vez. Esto evita que varios agentes hablen simultáneamente y creen una cacofonía ininteligible. Las solicitudes posteriores esperarán en una cola hasta que se complete la voz actual.

Protección multi-instancia: el mutex funciona tanto dentro de un único proceso de servidor MCP como entre múltiples instancias de Claude Desktop. Cuando se ejecutan varios terminales de Claude Desktop, se coordinan mediante un bloqueo de archivo a nivel de sistema para evitar superposiciones de voz.

Para permitir operaciones TTS concurrentes (múltiples voces reproduciéndose simultáneamente):

Variable de entorno:

export MCP_TTS_ALLOW_CONCURRENT=true

Opción de línea de comandos:

mcp-tts --sequential-tts=false

Nota: El TTS concurrente puede provocar audio superpuesto difícil de entender. Use esta opción solo cuando desee explícitamente que varias operaciones TTS se ejecuten simultáneamente.

Suprimir la salida "Hablando:"

De forma predeterminada, las herramientas TTS devuelven un mensaje como "Hablando: [texto]" cuando se completa la voz. Esto puede interferir con las respuestas del LLM. Para suprimir esta salida:

Variable de entorno:

export MCP_TTS_SUPPRESS_SPEAKING_OUTPUT=true

Opción de línea de comandos:

mcp-tts --suppress-speaking-output

Cuando está habilitado, las herramientas devuelven "Voz completada" en lugar de repetir el texto hablado.

Guardar audio en disco

Guarde la salida de audio TTS en archivos en lugar de (o además de) reproducirlos:

Variables de entorno:

export MCP_TTS_OUTPUT_DIR=/path/to/audio    # Save audio files to this directory
export MCP_TTS_NO_PLAY=true                  # Skip playback, only save (optional)

Opciones de línea de comandos:

mcp-tts --output-dir /path/to/audio          # Save and play
mcp-tts --output-dir /path/to/audio --no-play  # Save only, no playback

Los archivos se guardan con nombres únicos: tts_{timestamp}_{hash}.{ext}

Proveedor	Formato
macOS say	AIFF
Voice	Solo reproducción
ElevenLabs	MP3
Google TTS	WAV
OpenAI TTS	MP3

Primeros pasos

Instalación

go install github.com/blacktop/mcp-tts@latest

❱ mcp-tts --help

TTS (text-to-speech) MCP Server.

Provides multiple text-to-speech services via MCP protocol:

• say_tts - Uses macOS built-in 'say' command (macOS only)
• voice_tts - Uses local Qwen3-TTS through voice-say (when available on PATH)
• elevenlabs_tts - Uses ElevenLabs API for high-quality speech synthesis
• google_tts - Uses Google's Gemini TTS models for natural speech
• openai_tts - Uses OpenAI's TTS API with various voice options

Each tool supports different voices, rates, and configuration options.
Requires appropriate API keys for cloud-based services.

Designed to be used with the MCP (Model Context Protocol).

Usage:
  mcp-tts [flags]

Flags:
  -h, --help                       help for mcp-tts
      --no-play                    Skip playback, only save (requires --output-dir)
      --output-dir string          Save audio files to directory (env: MCP_TTS_OUTPUT_DIR)
      --sequential-tts             Enforce sequential TTS (prevent concurrent speech) (default true)
      --suppress-speaking-output   Suppress 'Speaking:' text output
  -v, --verbose                    Enable verbose debug logging

Configuración

Claude Desktop

Añada a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "say": {
      "command": "mcp-tts",
      "env": {
        "ELEVENLABS_API_KEY": "********",
        "ELEVENLABS_VOICE_ID": "EXAVITQu4vr4xnSDxMaL",
        "GOOGLE_AI_API_KEY": "********",
        "OPENAI_API_KEY": "********",
        "OPENAI_TTS_INSTRUCTIONS": "Speak in a cheerful and positive tone",
        "MCP_TTS_SUPPRESS_SPEAKING_OUTPUT": "true",
        "MCP_TTS_ALLOW_CONCURRENT": "false"
      }
    }
  }
}

Claude Code

claude mcp add say \
  -e GOOGLE_AI_API_KEY=your_key \
  -e ELEVENLABS_API_KEY=your_key \
  -e OPENAI_API_KEY=your_key \
  -- mcp-tts

Codex CLI

codex mcp add say \
  --env GOOGLE_AI_API_KEY=your_key \
  --env ELEVENLABS_API_KEY=your_key \
  --env OPENAI_API_KEY=your_key \
  -- mcp-tts

Gemini CLI

gemini mcp add say mcp-tts \
  -e GOOGLE_AI_API_KEY=your_key \
  -e ELEVENLABS_API_KEY=your_key \
  -e OPENAI_API_KEY=your_key

O añada manualmente a ~/.gemini/settings.json (o .gemini/settings.json en la raíz del proyecto):

{
  "mcpServers": {
    "say": {
      "command": ["mcp-tts"],
      "env": {
        "GOOGLE_AI_API_KEY": "..."
      }
    }
  }
}

Variables de entorno

ELEVENLABS_API_KEY: Su clave API de ElevenLabs (requerida para elevenlabs_tts)
ELEVENLABS_VOICE_ID: ID de voz de ElevenLabs (opcional, predeterminado a la voz predefinida "Sarah" EXAVITQu4vr4xnSDxMaL). Las claves API de nivel gratuito solo pueden usar voces predefinidas; las voces de la Biblioteca de voces (comunidad/profesional) devuelven 402 paid_plan_required.
GOOGLE_AI_API_KEY o GEMINI_API_KEY: Su clave API de Google AI (requerida para google_tts)
OPENAI_API_KEY: Su clave API de OpenAI (requerida para openai_tts)
OPENAI_TTS_INSTRUCTIONS: Instrucciones de voz personalizadas para OpenAI TTS (opcional, p. ej., "Habla con un tono alegre y positivo")
MCP_TTS_SUPPRESS_SPEAKING_OUTPUT: Establezca en "true" para suprimir la salida "Hablando:" (opcional)
MCP_TTS_ALLOW_CONCURRENT: Establezca en "true" para permitir operaciones TTS concurrentes (opcional, predeterminado secuencial)
MCP_TTS_OUTPUT_DIR: Directorio para guardar archivos de audio (opcional)
MCP_TTS_NO_PLAY: Establezca en "true" para omitir la reproducción al guardar (opcional, requiere MCP_TTS_OUTPUT_DIR)
MCP_TTS_ELICIT: Establezca en "true" para habilitar indicaciones interactivas de elicitación (también --elicit; opcional, desactivado por defecto). Cuando está desactivado, las herramientas usan argumentos explícitos/predeterminados sin preguntar; recomendado para uso con agentes.

Prueba

Probar TTS de macOS

❱ cat test/say.json | go run main.go --verbose

2025/03/23 22:41:49 INFO Starting MCP server name="Say TTS Service" version=1.0.0
2025/03/23 22:41:49 DEBU Say tool called request="{Request:{Method:tools/call Params:{Meta:<nil>}} Params:{Name:say_tts Arguments:map[text:Hello, world!] Meta:<nil>}}"
2025/03/23 22:41:49 DEBU Executing say command args="[--rate 200 Hello, world!]"
2025/03/23 22:41:49 INFO Speaking text text="Hello, world!"

{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Speaking: Hello, world!"}]}}

Probar TTS de Google

❱ cat test/google_tts.json | go run main.go --verbose

2025/05/23 18:26:45 INFO Starting MCP server name="Say TTS Service" version=""
2025/05/23 18:26:45 DEBU Google TTS tool called request="{...}"
2025/05/23 18:26:45 DEBU Generating TTS audio model=gemini-3.1-flash-tts-preview voice=Kore text="Hello! This is a test of Google's TTS API. How does it sound?"
2025/05/23 18:26:49 INFO Playing TTS audio via beep speaker bytes=181006
2025/05/23 18:26:53 INFO Speaking via Google TTS text="Hello! This is a test of Google's TTS API. How does it sound?" voice=Kore

{"jsonrpc":"2.0","id":4,"result":{"content":[{"type":"text","text":"Speaking: Hello! This is a test of Google's TTS API. How does it sound? (via Google TTS with voice Kore)"}]}}

Probar TTS de OpenAI

❱ cat test/openai_tts.json | go run main.go --verbose

2025/05/23 19:15:32 INFO Starting MCP server name="Say TTS Service" version=""
2025/05/23 19:15:32 DEBU OpenAI TTS tool called request="{...}"
2025/05/23 19:15:32 DEBU Generating OpenAI TTS audio model=tts-1 voice=nova speed=1.2 text="Hello! This is a test of OpenAI's text-to-speech API. I'm using the nova voice at 1.2x speed."
2025/05/23 19:15:34 DEBU Decoding MP3 stream from OpenAI
2025/05/23 19:15:34 DEBU Initializing speaker for OpenAI TTS sampleRate=22050
2025/05/23 19:15:36 INFO Speaking text via OpenAI TTS text="Hello! This is a test of OpenAI's text-to-speech API. I'm using the nova voice at 1.2x speed." voice=nova model=tts-1 speed=1.2

{"jsonrpc":"2.0","id":5,"result":{"content":[{"type":"text","text":"Speaking: Hello! This is a test of OpenAI's text-to-speech API. I'm using the nova voice at 1.2x speed. (via OpenAI TTS with voice nova)"}]}}

Probar el comportamiento del mutex con múltiples solicitudes TTS

# Sequential mode (default) - speeches play one after another
cat test/sequential.json | go run main.go --verbose

# Concurrent mode - allows overlapping speech  
cat test/sequential.json | go run main.go --verbose --sequential-tts=false

Habilidad: `speak`

Este repositorio incluye una habilidad speak que anuncia automáticamente planes, problemas y resúmenes en voz alta mediante TTS. Usa por defecto la voz say de macOS del host, y puede asignar opcionalmente voces distintas por proyecto o tipo de mensaje para que pueda identificar quién habla desde otra habitación.

Las habilidades siguen el estándar abierto Agent Skills y funcionan en Claude Code, Codex CLI y Gemini CLI.

Instalar la habilidad

skills.sh

npx skills add https://github.com/blacktop/mcp-tts --skill speak

Claude Code

Mediante el mercado de plugins (recomendado):

claude plugin marketplace add blacktop/mcp-tts
claude plugin install speak@mcp-tts

O manualmente:

mkdir -p ~/.claude/skills
git clone https://github.com/blacktop/mcp-tts.git /tmp/mcp-tts
cp -r /tmp/mcp-tts/skill ~/.claude/skills/speak

La habilidad ya está disponible. Claude la usará automáticamente cuando sea relevante, o invóquela directamente con /speak.

Codex CLI

Usando el instalador de habilidades (dentro de una sesión de Codex):

$skill-installer install the speak skill from https://github.com/blacktop/mcp-tts --path skill

O manualmente:

mkdir -p ~/.codex/skills
git clone https://github.com/blacktop/mcp-tts.git /tmp/mcp-tts
cp -r /tmp/mcp-tts/skill ~/.codex/skills/speak

Reinicie Codex después de instalar.

Gemini CLI

Gemini CLI usa extensiones para agrupar habilidades. Instale este repositorio como una extensión:

gemini extensions install https://github.com/blacktop/mcp-tts.git

Esto instala la habilidad speak.

O manualmente (solo la habilidad):

mkdir -p ~/.gemini/skills
git clone https://github.com/blacktop/mcp-tts.git /tmp/mcp-tts
cp -r /tmp/mcp-tts/skill ~/.gemini/skills/speak

Nota: Las habilidades de Gemini CLI son experimentales. Actívelas mediante /settings → busque "Skills" → actívelas.

Directorio de habilidades compartido (opcional)

Para mantener una sola copia en todos los agentes, ejecute el script de instalación:

git clone https://github.com/blacktop/mcp-tts.git
cd mcp-tts
./install-skill.sh

Esto copia la habilidad a ~/.agents/skills/speak y crea enlaces simbólicos para Claude Code, Codex CLI y Gemini CLI.

Verificar la instalación

Agente	Comando
Claude Code	Pregunte "¿Qué habilidades están disponibles?" o escriba `/speak`
Codex CLI	Las habilidades se cargan automáticamente al reiniciar
Gemini CLI	`gemini extensions list` o consulte `/settings` para ver las habilidades

Cómo funciona

La habilidad debe seleccionarse después de:

Planificación completada - Cuando se finaliza un plan/lista de tareas
Problema resuelto - Cuando se resuelve una corrección de errores o un error
Resumen generado - Al completar una tarea importante
Operación larga cambia de estado - Cuando una fase de compilación, prueba, implementación, lanzamiento, investigación o monitoreo se completa o falla
Intervención humana necesaria - Cuando la aprobación, autenticación, acción manual o un presupuesto de reintentos agotado bloquea el progreso

La habilidad usa por defecto voz solo local sin probar credenciales: voice_tts para planes y resúmenes cuando Voice está registrado, y say_tts rápido para alertas urgentes o como respaldo. Ambos evitan las cuotas de API en la nube y mantienen el contenido hablado en el Mac. El TTS en la nube se usa solo después de una elección explícita del usuario o configuración guardada. Si ese proveedor en la nube alcanza una cuota, token, autenticación o falla de configuración, el TTS automático en la nube se desactiva para la sesión y la habilidad usa voz local—o permanece solo texto cuando no hay herramienta local disponible. Nunca prueba automáticamente los otros proveedores en la nube. Las correcciones puntuales del proveedor duran la sesión; la configuración se actualiza solo cuando el usuario pide recordar la elección. Para la identidad local say, deje voice sin establecer para usar la Voz del sistema del host a menos que el usuario haya seleccionado intencionalmente una voz instalada exacta.

Licencia

MIT

Text-to-Speech (TTS)

Documentación

mcp-tts

Servidor MCP para TTS (Texto a Voz)

¿Qué es? 🤔

say_tts

voice_tts

elevenlabs_tts

google_tts

openai_tts

Configuración

TTS secuencial vs. concurrente

Suprimir la salida "Hablando:"

Guardar audio en disco

Primeros pasos

Instalación

Configuración

Claude Desktop

Claude Code

Codex CLI

Gemini CLI

Variables de entorno

Prueba

Probar TTS de macOS

Probar TTS de Google

Probar TTS de OpenAI

Probar el comportamiento del mutex con múltiples solicitudes TTS

Habilidad: speak

Instalar la habilidad

skills.sh

Claude Code

Codex CLI

Gemini CLI

Directorio de habilidades compartido (opcional)

Verificar la instalación

Cómo funciona

Licencia

`say_tts`

`voice_tts`

`elevenlabs_tts`

`google_tts`

`openai_tts`

Habilidad: `speak`