CHeema-Text-to-Voice-MCP-Server

Cheema Text-to-Voice MCP Server

Cheema Text-to-Voice é um servidor MCP gratuito e de código aberto que dá a qualquer assistente de IA compatível com MCP, incluindo Claude Desktop, Claude Code e n8n, uma voz real. Ele executa os modelos de texto-para-fala NeuTTS localmente na sua própria CPU ou GPU, então não há chaves de API para configurar, nenhum serviço em nuvem no meio do caminho e nenhuma cobrança por caractere: o texto entra, um arquivo WAV sai, inteiramente na sua máquina. Peça ao seu assistente para falar e ele sintetiza fala natural em cinco vozes integradas em quatro idiomas, ou clona uma nova voz a partir de uma gravação curta em segundos.

---

Links

• Diretório MCP: listado em mcpservers.org
• Estudo de caso: como o Cheema Text-to-Voice foi construído

Construído por Tayyab Ilyas, Engenheiro de Agentes de IA em Barcelona.

---

O que ele pode fazer?

Basta pedir ao seu assistente de IA para falar, e ele cuida do resto:

"Diga olá em francês usando a voz juliette"

"Converta este parágrafo em fala e salve como intro.wav"

"Clone minha voz a partir desta gravação e use-a para ler meu ensaio"

Recursos:

• 5 vozes integradas em 4 idiomas: inglês (jo, dave), alemão (greta), francês (juliette), espanhol (mateo)
• Clonagem instantânea de voz a partir de uma amostra WAV de 3 a 15 segundos, persistida entre reinicializações
• 5 ferramentas MCP (tts_help, tts_list_speakers, tts_list_models, tts_synthesize, tts_add_speaker) mais 2 modelos de prompt prontos
• 3 transportes: stdio para Claude Desktop e Claude Code, SSE e Streamable HTTP para n8n e outros clientes remotos
• Modelos de backbone NeuTTS intercambiáveis, incluindo variantes GGUF quantizadas menores, com aceleração CUDA opcional
• 100% local: sem chaves de API, sem chamadas em nuvem, sem cobrança por caractere

---

Início Rápido

1. Instalar Pré-requisitos

Você precisa de Python 3.10+ e espeak-ng:

# Ubuntu / Debian
sudo apt install espeak-ng

# macOS
brew install espeak-ng

# Windows
choco install espeak-ng

2. Clonar e Instalar

git clone https://github.com/MuhammadTayyabIlyas/CHeema-Text-to-Voice-MCP-Server.git
cd CHeema-Text-to-Voice-MCP-Server

python -m venv venv
source venv/bin/activate        # Linux/macOS
# venv\Scripts\activate          # Windows

pip install -e .
pip install "mcp[cli]"

3. Conectar ao Seu Assistente de IA

Escolha sua plataforma e siga os passos abaixo.

---

Configuração por Plataforma

Claude Desktop

Adicione isto ao seu arquivo de configuração:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cheema-tts": {
      "command": "/full/path/to/CHeema-Text-to-Voice-MCP-Server/venv/bin/python",
      "args": ["/full/path/to/CHeema-Text-to-Voice-MCP-Server/mcp_server.py"],
      "env": {}
    }
  }
}

Reinicie o Claude Desktop. Você verá as ferramentas TTS aparecerem no menu de ferramentas.

Claude Code

claude mcp add cheema-tts -- /full/path/to/venv/bin/python /full/path/to/mcp_server.py

Depois, basta pedir ao Claude para gerar fala em qualquer conversa.

n8n

Inicie o servidor no modo SSE:

cd CHeema-Text-to-Voice-MCP-Server
source venv/bin/activate
python mcp_server.py --transport sse --host 127.0.0.1 --port 8000

No seu fluxo de trabalho n8n:

1. Adicione um nó AI Agent com uma MCP Client Tool
2. Defina o tipo de conexão como SSE
3. Insira a URL: http://127.0.0.1:8000/sse
4. O agente agora pode chamar qualquer ferramenta TTS

Qualquer Outro Cliente MCP

Inicie o servidor com o transporte de sua preferência:

# SSE (for web platforms and remote clients)
python mcp_server.py --transport sse --host 0.0.0.0 --port 8000

# Streamable HTTP
python mcp_server.py --transport streamable-http --host 0.0.0.0 --port 8000

Conecte seu cliente MCP a:

• SSE: http://<your-host>:8000/sse
• HTTP: http://<your-host>:8000/mcp

---

Vozes Disponíveis

Voz	Idioma	Descrição
jo	Inglês	Padrão: voz feminina clara e natural
dave	Inglês	Voz masculina
greta	Alemão	Voz feminina alemã
juliette	Francês	Voz feminina francesa
mateo	Espanhol	Voz masculina espanhola

Use tts_list_speakers para ver todas as vozes, incluindo as personalizadas que você adicionou.

---

Clonagem de Voz

Clone qualquer voz a partir de uma amostra de áudio curta:

1. Grave ou encontre um arquivo WAV: 3 a 15 segundos de fala limpa
2. Conheça a transcrição: as palavras exatas faladas na gravação
3. Peça ao seu assistente de IA:

"Adicione um novo locutor chamado 'alex' a partir de /path/to/recording.wav, com a transcrição 'Isto é o que eu disse na gravação'"

Ou chame a ferramenta diretamente:

tts_add_speaker(name="alex", wav_path="/path/to/recording.wav", ref_text="This is what I said in the recording")

Vozes personalizadas são salvas permanentemente e ficam disponíveis entre reinicializações.

Dicas para melhores resultados:

• Áudio mono, taxa de amostragem de 16-44 kHz
• 3 a 15 segundos de fala contínua e natural
• Ruído de fundo mínimo

---

Ferramentas Disponíveis

Ferramenta	O que faz
tts_help	Mostra um guia de uso completo com exemplos (comece aqui)
tts_synthesize	Converte texto em fala, salva um arquivo WAV
tts_list_speakers	Lista todas as vozes disponíveis
tts_list_models	Mostra o modelo ativo e alternativas
tts_add_speaker	Clona uma nova voz a partir de uma amostra de áudio

Parâmetros do tts_synthesize

Parâmetro	Obrigatório	Padrão	Descrição
text	Sim	nenhum	O texto a ser convertido em fala
speaker	Não	"jo"	Qual voz usar
output_filename	Não	gerado automaticamente	Nome de arquivo personalizado para a saída WAV

Prompts MCP (Modelos)

Prompt	Descrição
quick_speech	Geração rápida de fala: basta fornecer texto e locutor opcional
voice_clone_guide	Passo a passo para adicionar uma nova voz

Eles aparecem automaticamente no seletor de prompts do Claude Desktop.

---

Modelos

O modelo padrão (neutts-nano) funciona muito bem na CPU. Modelos maiores produzem qualidade superior, mas exigem mais recursos.

Modelo	Idioma	Tamanho	Observações
neuphonic/neutts-nano	Inglês	~229M	Padrão: rápido, boa qualidade
neuphonic/neutts-air	Inglês	~552M	Qualidade superior, mais lento
neuphonic/neutts-nano-german	Alemão	~229M	Idioma alemão
neuphonic/neutts-nano-french	Francês	~229M	Idioma francês
neuphonic/neutts-nano-spanish	Espanhol	~229M	Idioma espanhol
neuphonic/neutts-*-q4-gguf	varia	menor	Quantizado: mais rápido, menos memória
neuphonic/neutts-*-q8-gguf	varia	médio	Quantizado: equilibrado

Alterne os modelos usando variáveis de ambiente:

NEUTTS_BACKBONE="neuphonic/neutts-air" python mcp_server.py

---

Configuração

Todas as configurações são opcionais. Os padrões funcionam imediatamente.

Variável	Padrão	Descrição
NEUTTS_BACKBONE	neuphonic/neutts-nano	Repositório de modelo HuggingFace
NEUTTS_BACKBONE_DEVICE	cpu	cpu ou cuda para GPU
NEUTTS_CODEC	neuphonic/neucodec	Modelo de codec de áudio
NEUTTS_CODEC_DEVICE	cpu	cpu ou cuda para GPU
NEUTTS_OUTPUT_DIR	./output	Onde os arquivos WAV são salvos
NEUTTS_SAMPLES_DIR	./samples	Amostras de locutor integradas
NEUTTS_SPEAKERS_DIR	./speakers	Dados de voz personalizados
NEUTTS_TRANSPORT	stdio	stdio, sse ou streamable-http
NEUTTS_HOST	127.0.0.1	Endereço de bind (somente SSE/HTTP)
NEUTTS_PORT	8000	Porta de bind (somente SSE/HTTP)

Aceleração por GPU

Para síntese mais rápida em GPUs NVIDIA:

NEUTTS_BACKBONE_DEVICE=cuda NEUTTS_CODEC_DEVICE=cuda python mcp_server.py

Requer PyTorch com suporte a CUDA.

---

Executando como um Serviço

Para uso em produção, crie um serviço systemd para que ele inicie automaticamente:

# /etc/systemd/system/cheema-tts.service
[Unit]
Description=Cheema Text-to-Voice MCP Server
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/CHeema-Text-to-Voice-MCP-Server
ExecStart=/path/to/venv/bin/python mcp_server.py --transport sse --host 127.0.0.1 --port 8000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now cheema-tts

Para expô-lo via HTTPS, coloque um proxy reverso Nginx ou Caddy na frente com estas configurações-chave para SSE:

• Desative o buffer do proxy (proxy_buffering off)
• Defina um tempo limite de leitura longo (proxy_read_timeout 86400)
• Adicione o cabeçalho X-Accel-Buffering: no

---

Solução de Problemas

O servidor não inicia?

• Verifique o espeak-ng: espeak-ng --version
• Verifique as dependências: pip list | grep -E "mcp|neutts|torch|soundfile"

Sem saída de áudio?

• Verifique o diretório output/ para arquivos WAV
• Verifique o nome do locutor com tts_list_speakers

Primeira execução lenta?

• Normal: a primeira execução baixa os pesos do modelo do HuggingFace (~200-500MB). Em cache depois disso.

Quer aceleração por GPU?

• Defina NEUTTS_BACKBONE_DEVICE=cuda e NEUTTS_CODEC_DEVICE=cuda

---

Como Funciona

1. O servidor carrega o modelo de backbone NeuTTS e o codec de áudio na inicialização
2. As impressões de voz do locutor (arquivos .pt) são carregadas na memória
3. Quando você solicita fala, o texto é fonemizado e combinado com a referência de voz do locutor
4. O modelo gera tokens de fala, decodificados em uma forma de onda de 24kHz
5. A saída é salva como um arquivo WAV padrão

---

Estrutura do Projeto

CHeema-Text-to-Voice-MCP-Server/
├── mcp_server.py       # MCP server entry point
├── neutts/             # NeuTTS engine
├── samples/            # Built-in speaker voices (.wav, .pt, .txt)
├── speakers/           # Custom cloned voices (auto-created)
├── output/             # Generated audio files (auto-created)
└── examples/           # Usage examples

---

Créditos

• NeuTTS por Neuphonic, o motor de TTS
• Protocolo MCP por Anthropic, o padrão de ferramentas de IA

---

Autor

Tayyab Ilyas, Pesquisador de Doutorado e Fundador de EdTech

Construindo ferramentas com IA para educadores e pesquisadores.

---

Licença

Licença MIT. Os modelos NeuTTS subjacentes têm suas próprias licenças. Consulte o repositório NeuTTS para obter detalhes.

---

Cheema Text-to-Voice MCP Server
Dê uma voz ao seu assistente de IA.