Text to Speech

Servidor MCP de Texto para Fala

Dê voz ao seu assistente de IA — localmente, sem chave de API, sem conta e sem serviço em nuvem.

Text to Speech é um servidor de código aberto do Model Context Protocol (MCP) que permite que assistentes de IA leiam texto em voz alta no computador do usuário. Ele usa o sintetizador de fala já presente no sistema operacional do host, então nada que você pedir para dizer sai da sua máquina.

Funciona em Windows, macOS e Linux. A instalação é uma linha:

uvx text-to-speech-mcp

O servidor expõe uma ferramenta controlada por modelo:

speak_text(text: string)

Use-a para texto fornecido pelo usuário, respostas do assistente, fluxos de acessibilidade ou atualizações de progresso faladas enquanto um agente trabalha.

Por que este

A maioria dos servidores MCP de texto para fala envolve uma API de nuvem, o que significa conta, chave, cobrança por caractere e seu texto saindo da máquina. Este usa o mecanismo de fala que seu sistema operacional já inclui, então funciona offline, não custa nada e mantém o texto local — o que importa se você trabalha em qualquer lugar que regule onde os dados podem ir.

Ele também inclui uma habilidade de narração para agentes, para que um assistente saiba como narrar, não apenas que pode.

Recursos

• Reprodução local por meio do sintetizador integrado da plataforma por padrão: Windows SAPI, macOS say ou espeak-ng no Linux.
• Sem API de nuvem e sem chave de API na configuração padrão.
• Reprodução FIFO: solicitações simultâneas são faladas uma de cada vez, em ordem.
• Conclusão de ferramenta bloqueante: cada chamada retorna após o término do áudio.
• Tamanho limitado de entrada e de fila para evitar uso ilimitado de recursos.
• Arquivos WAV temporários gerados são removidos após a reprodução por padrão.
• Transporte MCP padrão stdio por meio do SDK oficial do Python.
• Backends opcionais Piper, Transformers MMS e HTTP local para usuários avançados.

O código-fonte do servidor MCP é de código aberto sob a Licença MIT. Windows SAPI e o comando say do macOS são componentes proprietários de seus sistemas operacionais; não são mecanismos de fala de código aberto. espeak-ng é software de código aberto licenciado separadamente.

Requisitos

• Python 3.10 ou mais recente.
• Um cliente MCP compatível com servidores MCP via stdio.
• uv/uvx é recomendado para instalação de pacotes via MCP.

Por plataforma, para o padrão de zero configuração:

Plataforma	Síntese	Reprodução	Instalação extra
Windows 10/11	SAPI via PowerShell	System.Media.SoundPlayer	Nenhuma
macOS	say	afplay	Nenhuma
Linux / outros Unix	espeak-ng ou espeak	aplay, paplay, play ou ffplay	espeak-ng e um reprodutor

No Debian ou Ubuntu, isso geralmente é:

sudo apt install espeak-ng alsa-utils

Defina TEXT_TO_SPEECH_BACKEND ou TEXT_TO_SPEECH_PLAYER para substituir qualquer uma das escolhas. Se um comando obrigatório estiver ausente, o servidor informa qual é e como instalá-lo, em vez de falhar silenciosamente.

Instalação

Configure um cliente MCP para executar o pacote PyPI publicado:

uvx text-to-speech-mcp

Para clientes MCP que aceitam configuração de servidor baseada em comando, use:

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

Alguns clientes usam TOML, JSON ou uma página de configurações gráfica. Use uvx text-to-speech-mcp como o comando do servidor e reinicie o cliente após alterar a configuração.

Instalar a partir do código-fonte

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

Em seguida, configure o cliente para executar text-to-speech-mcp diretamente.

Exemplos de prompt

Ler texto arbitrário:

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

Ler a resposta final:

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

Ler as atualizações de progresso intermediárias visíveis em ordem:

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.

A parte text_to_speech é um exemplo de nome de servidor do lado do cliente. Os clientes podem exibir um namespace diferente mantendo o nome da ferramenta speak_text.

Contrato da ferramenta

Campo	Valor
Nome da ferramenta	speak_text
Entrada	text, string obrigatória, 1–50.000 caracteres
Resultado	Mensagem de conclusão após o término da reprodução local
Ordenação	FIFO, uma reprodução ativa por vez
Limite da fila	32 solicitações pendentes
Uso de rede com backend integrado	Nenhum

A ferramenta é controlada por modelo sob o MCP. O usuário decide quando pedir ao modelo para chamá-la, e o cliente MCP pode mostrar ou exigir aprovação para chamadas de ferramenta.

Privacidade

Com qualquer um dos backends integrados, o texto é passado do cliente MCP para um processo Python local e depois para os componentes de fala do sistema operacional. Ele não é enviado para este projeto, uma API externa ou um provedor de TTS em nuvem. Arquivos WAV gerados são gravados em um diretório text-to-speech-mcp dentro do diretório temporário do sistema (%TEMP% no Windows, /tmp no macOS e Linux) e excluídos após a reprodução, a menos que TEXT_TO_SPEECH_KEEP_AUDIO=true esteja definido.

O backend http é a exceção: se o texto sai da máquina depende inteiramente do endpoint que você configurar.

Não peça a um assistente de IA para falar segredos, credenciais, chaves privadas, raciocínio oculto ou saída sensível de ferramentas.

Backends opcionais

O padrão não requer configuração. TEXT_TO_SPEECH_BACKEND não está definido e o servidor seleciona sapi, say ou espeak para corresponder à plataforma do host.

Para fixar um explicitamente, ou para usar um backend que não está integrado ao SO, defina TEXT_TO_SPEECH_BACKEND para sapi, say, espeak, piper, transformers_mms ou http. Os três últimos exigem seu próprio modelo local, binário, dependências Python ou endpoint. TEXT_TO_SPEECH_FALLBACK_BACKEND nomeia um segundo backend a ser tentado se o primeiro falhar. Consulte configuração do backend.

Habilidade de narração para agentes

Uma ferramenta de fala sozinha não diz ao assistente quando ou como falar. Deixados à improvisação, os agentes narram raciocínio oculto, pulam as partes que você realmente precisava ou leem uma paráfrase em vez do que está na tela.

skills/project-tts-responder/SKILL.md é uma política de narração pronta construída sobre speak_text. Copie-a para o diretório .claude/skills/ do seu projeto:

Modo	Comportamento
Lote (padrão)	Uma reprodução no final de um turno, cobrindo todas as atualizações visíveis mais a resposta final
Streaming	Narrar cada atualização conforme ela aparece — bom para demonstrações e passos guiados
Ler sob demanda	Ler um arquivo nomeado ou bloco de texto textualmente

Ele também lida com as partes fáceis de errar:

• Perguntas interativas são narradas antes de o seletor abrir. Uma ferramenta de pergunta interativa é em si a pausa, e suas opções vivem nos parâmetros da ferramenta, não no texto visível — então qualquer regra que narre "quando as opções estiverem visíveis" dispara apenas depois que o usuário já respondeu. Essa é a forma mais comum de a narração falhar silenciosamente.
• Fala exatamente o que está na tela, nunca uma paráfrase.
• Nunca fala raciocínio oculto, segredos, credenciais ou saída bruta de ferramentas.
• Uma chamada de reprodução por turno, nunca em paralelo, com comportamento definido quando uma chamada falha.

A habilidade se aplica quando você pede áudio. Para fazer um projeto narrar cada resposta, diga isso nas instruções do agente do próprio projeto — por exemplo, "narrar cada resposta no modo Lote, a menos que eu opte por sair".

Compatibilidade com MCP

• Transporte MCP: stdio
• Implementação de ferramenta MCP: SDK oficial de MCP para Python
• Metadados de registro: server.json usando o esquema de 2025-12-11
• Registro de pacotes: PyPI
• Marcador de propriedade do registro: comentário mcp-name deste README
• Namespace do registro: io.github.Engr-FaizanAli/text-to-speech

Licença

MIT. Consulte LICENSE.