Text-to-Speech (TTS)

Um servidor de Text-to-Speech que suporta múltiplos backends como macOS say, ElevenLabs, Google Gemini e OpenAI TTS.

GitHub

Experimente este MCPPatrocinado

Documentação

mcp-tts

MCP Server for TTS (Text-to-Speech)

O quê? 🤔

Adiciona Text-to-Speech a ferramentas como Claude Desktop e Cursor IDE.

Ele registra as ferramentas TTS existentes, além de voice_tts quando voice-say está disponível em PATH:

say_tts
voice_tts (quando disponível)
elevenlabs_tts
google_tts
openai_tts

`say_tts`

Usa o binário macOS say para falar o texto com vozes de sistema integradas

`voice_tts`

Usa a CLI local voice-say do Voice para executar Qwen3-TTS via MLX. Voice não requer chave de API e mantém texto e áudio no Mac. O modelo é recarregado a cada chamada, então a inicialização normalmente leva alguns segundos; prefira-o para resumos e avisos em vez de alertas críticos de tempo.

A ferramenta é registrada apenas quando voice-say é resolvível em PATH. Os parâmetros opcionais são:

voice: voz predefinida Ryan ou Aiden
tier: small para síntese mais rápida 0.6B ou large para síntese 1.7B de maior qualidade
style: orientações de entrega em texto livre
describe: design de voz em texto livre; força o modelo 1.7B e não pode ser combinado com voice

Voice reproduz áudio diretamente e não suporta --output-dir; com --no-play, as chamadas falham sem iniciar o voice-say.

[!WARNING] O repositório Voice é atualmente privado e será lançado publicamente em breve, então o link requer acesso por enquanto.

`elevenlabs_tts`

Usa a API de text-to-speech ElevenLabs para falar o texto com vozes premium de IA

`google_tts`

Usa os modelos TTS Gemini do Google para falar o texto com 30 vozes de alta qualidade. As vozes disponíveis incluem:

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`

Usa a API de Text-to-Speech da OpenAI para falar o texto com 10 vozes com som natural:

alloy (Calorosa, conversacional, moderna)
ash (Confiante, assertiva, levemente texturizada)
ballad (Suave, melodiosa, levemente lírica)
coral (Alegre, fresca, otimista)
echo (Neutra, calma, equilibrada)
fable (Contadora de histórias, expressiva)
nova (Clara, precisa, levemente formal)
onyx (Profunda, autoritária, ressonante)
sage (Calmante, empática, reconfortante)
shimmer (Brilhante, animada, brincalhona)
verse (Versátil, expressiva)

Suporta três modelos de qualidade:

gpt-4o-mini-tts - Padrão, qualidade e velocidade otimizadas
tts-1 - Qualidade padrão, geração mais rápida
tts-1-hd - Áudio em alta definição, qualidade premium

Recursos adicionais:

Controle de velocidade de 0.25x a 4.0x (padrão: 1.0x)
Instruções de voz personalizadas (ex.: "Fale em um tom alegre e positivo") via parâmetro ou variável de ambiente OPENAI_TTS_INSTRUCTIONS

Configuração

TTS Sequencial vs. Concorrente

Por padrão, o servidor TTS impõe operações de fala sequenciais — apenas uma solicitação TTS pode reproduzir áudio por vez. Isso impede que vários agentes falem simultaneamente e criem uma cacofonia ininteligível. Solicitações subsequentes aguardarão em uma fila até que a fala atual termine.

Proteção Multi-Instância: O mutex funciona tanto dentro de um único processo do servidor MCP quanto entre várias instâncias do Claude Desktop. Ao executar vários terminais Claude Desktop, eles se coordenam por meio de um bloqueio de arquivo em todo o sistema para evitar sobreposição de fala.

Para permitir operações TTS concorrentes (vários áudios tocando simultaneamente):

Variável de Ambiente:

export MCP_TTS_ALLOW_CONCURRENT=true

Flag de Linha de Comando:

mcp-tts --sequential-tts=false

Nota: TTS concorrente pode resultar em áudio sobreposto difícil de entender. Use esta opção somente quando desejar explicitamente que várias operações TTS sejam executadas simultaneamente.

Suprimindo a Saída "Falando:"

Por padrão, as ferramentas TTS retornam uma mensagem como "Falando: [texto]" quando a fala é concluída. Isso pode interferir nas respostas do LLM. Para suprimir essa saída:

Variável de Ambiente:

export MCP_TTS_SUPPRESS_SPEAKING_OUTPUT=true

Flag de Linha de Comando:

mcp-tts --suppress-speaking-output

Quando habilitado, as ferramentas retornam "Fala concluída" em vez de ecoar o texto falado.

Salvando Áudio em Disco

Salve a saída de áudio TTS em arquivos em vez de (ou além de) reproduzi-los:

Variáveis de Ambiente:

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)

Flags de Linha de Comando:

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

Os arquivos são salvos com nomes exclusivos: tts_{timestamp}_{hash}.{ext}

Provedor	Formato
macOS say	AIFF
Voice	Somente reprodução
ElevenLabs	MP3
Google TTS	WAV
OpenAI TTS	MP3

Primeiros Passos

Instalação

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

Configuração

Claude Desktop

Adicione 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

Ou adicione manualmente a ~/.gemini/settings.json (ou .gemini/settings.json na raiz do projeto):

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

Variáveis de Ambiente

ELEVENLABS_API_KEY: Sua chave de API do ElevenLabs (obrigatória para elevenlabs_tts)
ELEVENLABS_VOICE_ID: ID da voz do ElevenLabs (opcional, padrão é a voz pré-fabricada "Sarah" EXAVITQu4vr4xnSDxMaL). Chaves de API do nível gratuito só podem usar vozes pré-fabricadas — vozes da Biblioteca de Voz (comunitária/profissional) retornam 402 paid_plan_required.
GOOGLE_AI_API_KEY ou GEMINI_API_KEY: Sua chave de API do Google AI (obrigatória para google_tts)
OPENAI_API_KEY: Sua chave de API da OpenAI (obrigatória para openai_tts)
OPENAI_TTS_INSTRUCTIONS: Instruções de voz personalizadas para TTS da OpenAI (opcional, ex.: "Fale em um tom alegre e positivo")
MCP_TTS_SUPPRESS_SPEAKING_OUTPUT: Defina como "true" para suprimir a saída "Falando:" (opcional)
MCP_TTS_ALLOW_CONCURRENT: Defina como "true" para permitir operações TTS concorrentes (opcional, padrão é sequencial)
MCP_TTS_OUTPUT_DIR: Diretório para salvar arquivos de áudio (opcional)
MCP_TTS_NO_PLAY: Defina como "true" para pular a reprodução ao salvar (opcional, requer MCP_TTS_OUTPUT_DIR)
MCP_TTS_ELICIT: Defina como "true" para habilitar prompts de elicitação interativos (também --elicit; opcional, padrão desativado). Quando desativado, as ferramentas usam argumentos/padrões explícitos sem prompts — recomendado para uso de agentes.

Teste

Testar TTS do 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!"}]}}

Testar TTS do 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)"}]}}

Testar TTS da 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)"}]}}

Testar o comportamento do mutex com múltiplas solicitações 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

Habilidade: `speak`

Este repositório inclui uma habilidade speak que anuncia planos, problemas e resumos em voz alta automaticamente usando TTS. Ela usa por padrão a voz macOS say do host e pode opcionalmente atribuir vozes distintas por projeto ou tipo de mensagem para que você possa identificar quem está falando de outro cômodo.

As habilidades seguem o padrão aberto Agent Skills e funcionam em Claude Code, Codex CLI e Gemini CLI.

Instalar Habilidade

skills.sh

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

Claude Code

Via Plugin Marketplace (recomendado):

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

Ou 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

A habilidade agora está disponível. Claude a usará automaticamente quando relevante, ou invoque diretamente com /speak.

Codex CLI

Usando o instalador de habilidades (dentro de uma sessão Codex):

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

Ou 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 o Codex após a instalação.

Gemini CLI

O Gemini CLI usa extensões para agrupar habilidades. Instale este repositório como uma extensão:

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

Isso instala a habilidade speak.

Ou manualmente (somente habilidade):

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: As habilidades do Gemini CLI são experimentais. Ative através de /settings → pesquise "Skills" → ative.

Diretório de Habilidades Compartilhado (Opcional)

Para manter uma única cópia em todos os agentes, execute o script de instalação:

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

Isso copia a habilidade para ~/.agents/skills/speak e cria links simbólicos para Claude Code, Codex CLI e Gemini CLI.

Verificar Instalação

Agente	Comando
Claude Code	Pergunte "Quais habilidades estão disponíveis?" ou digite `/speak`
Codex CLI	As habilidades carregam automaticamente na reinicialização
Gemini CLI	`gemini extensions list` ou verifique `/settings` para habilidades

Como Funciona

A habilidade deve ser selecionada após:

Planejamento concluído - Quando um plano/lista de tarefas é finalizado
Problema resolvido - Quando uma correção de bug ou erro é resolvida
Resumo gerado - Ao concluir uma tarefa importante
Operação longa muda de estado - Quando uma fase de compilação, teste, implantação, lançamento, pesquisa ou monitoramento é concluída ou falha
Intervenção humana necessária - Quando aprovação, autenticação, ação manual ou um orçamento de tentativas esgotado bloqueiam o progresso

A habilidade usa por padrão fala somente local sem verificar credenciais: voice_tts para planos e resumos quando Voice está registrado, e say_tts rápido para alertas urgentes ou como fallback. Ambos evitam cotas de API em nuvem e mantêm o conteúdo falado no Mac. TTS em nuvem é usado apenas após uma escolha explícita do usuário ou configuração salva. Se esse provedor de nuvem atingir uma cota, token, autenticação ou falha de configuração, o TTS automático em nuvem é desativado para a sessão e a habilidade usa fala local—ou permanece somente texto quando nenhuma ferramenta local está disponível. Nunca tenta os outros provedores de nuvem automaticamente. Correções de provedor pontuais duram a sessão; a configuração é atualizada apenas quando o usuário pede para lembrar a escolha. Para identidade local say, deixe voice não definido para usar a Voz do Sistema do host, a menos que o usuário tenha selecionado intencionalmente uma voz instalada exata.

Licença

MIT

Text-to-Speech (TTS)

Documentação

mcp-tts

MCP Server for TTS (Text-to-Speech)

O quê? 🤔

say_tts

voice_tts

elevenlabs_tts

google_tts

openai_tts

Configuração

TTS Sequencial vs. Concorrente

Suprimindo a Saída "Falando:"

Salvando Áudio em Disco

Primeiros Passos

Instalação

Configuração

Claude Desktop

Claude Code

Codex CLI

Gemini CLI

Variáveis de Ambiente

Teste

Testar TTS do macOS

Testar TTS do Google

Testar TTS da OpenAI

Testar o comportamento do mutex com múltiplas solicitações TTS

Habilidade: speak

Instalar Habilidade

skills.sh

Claude Code

Codex CLI

Gemini CLI

Diretório de Habilidades Compartilhado (Opcional)

Verificar Instalação

Como Funciona

Licença

`say_tts`

`voice_tts`

`elevenlabs_tts`

`google_tts`

`openai_tts`

Habilidade: `speak`