MCP TTS VOICEVOX

Exemplos de instalação:

• Windows (qualquer um destes)

  • Winget: winget install --id=Gyan.FFmpeg -e
  • Chocolatey: choco install ffmpeg
  • Scoop: scoop install ffmpeg
  • Builds oficiais: Baixe de https://www.gyan.dev/ffmpeg/builds/ ou https://github.com/BtbN/FFmpeg-Builds e adicione a pasta bin ao PATH

• macOS

  • Homebrew: brew install ffmpeg

• Linux

  • Debian/Ubuntu: sudo apt-get update && sudo apt-get install -y ffmpeg
  • Fedora: sudo dnf install -y ffmpeg
  • Arch: sudo pacman -S ffmpeg

Configuração do PATH:

• Windows: Adicione ...\ffmpeg\bin às variáveis de ambiente e reinicie o PowerShell/terminal e o editor (Claude/VS Code, etc.)
  • Verifique: powershell -c "$env:Path" deve incluir o caminho do ffmpeg
• macOS/Linux: Geralmente detectado automaticamente. Verifique com echo $PATH se necessário, reinicie o shell.
• Clientes MCP (Claude Desktop/Code): Reinicie o app para recarregar o PATH.

Verificação:

ffplay -version

Se as informações de versão forem exibidas, a instalação está concluída. CLI/MCP detectarão automaticamente o ffplay e usarão reprodução em streaming via stdin.

Ferramentas de dicionário do usuário (grupo dictionary):

Qualquer ferramenta pode ser desativada individualmente com --disable-tools / VOICEVOX_DISABLED_TOOLS, ou por grupo com --disable-groups / VOICEVOX_DISABLED_GROUPS.

Configurações do VOICEVOX

Opções de Reprodução

Configurações de Restrição

Restrinja a IA de especificar certas opções.

Desativar Ferramentas

# Disable individual tools
export VOICEVOX_DISABLED_TOOLS=speak_player,synthesize_file

# Disable a built-in group of tools
export VOICEVOX_DISABLED_GROUPS=player

# Combine groups and individual tools
export VOICEVOX_DISABLED_GROUPS=dictionary
export VOICEVOX_DISABLED_TOOLS=synthesize_file

Grupos integrados para VOICEVOX_DISABLED_GROUPS / --disable-groups:

Configurações do Player na Interface

Configurações de Saída de Arquivos

Configurações do Servidor

Os argumentos de linha de comando têm prioridade sobre as variáveis de ambiente. A lista completa e atualizada de opções está sempre disponível via npx @kajidog/mcp-tts-voicevox --help.

# Basic settings
npx @kajidog/mcp-tts-voicevox --url http://192.168.1.100:50021 --speaker 3 --speed 1.2

# HTTP mode
npx @kajidog/mcp-tts-voicevox --http --port 8080

# With restrictions
npx @kajidog/mcp-tts-voicevox --restrict-immediate --restrict-wait-for-end

# Disable individual tools
npx @kajidog/mcp-tts-voicevox --disable-tools speak_player,synthesize_file

# Disable a tool group
npx @kajidog/mcp-tts-voicevox --disable-groups player

Você pode usar um arquivo de configuração JSON em vez de (ou em adição a) variáveis de ambiente e argumentos de CLI. Isso é útil quando você tem muitas configurações para definir.

Ordem de prioridade: Argumentos de CLI > Variáveis de ambiente > Arquivo de configuração > Padrões

Gerar um arquivo de configuração

npx @kajidog/mcp-tts-voicevox --init

Isso cria .voicevoxrc.json no diretório atual com todas as configurações padrão. Edite conforme necessário.

Usar um caminho personalizado para o arquivo de configuração

npx @kajidog/mcp-tts-voicevox --config ./my-config.json

Ou via variável de ambiente:

VOICEVOX_CONFIG=./my-config.json npx @kajidog/mcp-tts-voicevox

Exemplo de .voicevoxrc.json

{
  "url": "http://192.168.1.50:50021",
  "speaker": 3,
  "speed": 1.2,
  "http": true,
  "port": 8080,
  "disable-tools": ["synthesize_file"],
  "disable-groups": ["dictionary"]
}

As chaves podem ser escritas em kebab-case (use-streaming), camelCase (useStreaming) ou nomes internos de chaves (defaultSpeaker). Se .voicevoxrc.json existir no diretório atual, ele é carregado automaticamente.

Para conexões remotas:

Iniciar servidor:

# Linux/macOS
MCP_HTTP_MODE=true MCP_HTTP_PORT=3000 npx @kajidog/mcp-tts-voicevox

# Windows PowerShell
$env:MCP_HTTP_MODE='true'; $env:MCP_HTTP_PORT='3000'; npx @kajidog/mcp-tts-voicevox

Configuração do Claude Desktop (usando mcp-remote):

{
  "mcpServers": {
    "tts-mcp-proxy": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/mcp"]
    }
  }
}

Configurações de Locutor por Projeto

Com o Claude Code, você pode configurar diferentes locutores padrão por projeto usando cabeçalhos personalizados em .mcp.json:

Exemplo de .mcp.json:

{
  "mcpServers": {
    "tts": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "X-Voicevox-Speaker": "113",
        "X-API-Key": "your-api-key"
      }
    }
  }
}

Isso permite que cada projeto use um personagem de voz diferente automaticamente.

Ordem de prioridade:

1. Parâmetro explícito speaker na chamada da ferramenta (maior)
2. Padrão do projeto do cabeçalho X-Voicevox-Speaker
3. Configuração global VOICEVOX_DEFAULT_SPEAKER (menor)

Conectando do WSL a um servidor MCP em execução no Windows:

1. Obter o IP do Host Windows a partir do WSL

# Method 1: From default gateway
ip route show | grep -oP 'default via \K[\d.]+'
# Usually in the format 172.x.x.1

# Method 2: From /etc/resolv.conf (WSL2)
cat /etc/resolv.conf | grep nameserver | awk '{print $2}'

2. Iniciar o Servidor no Windows

Adicione o IP do gateway WSL a MCP_ALLOWED_HOSTS para permitir acesso a partir do WSL:

$env:MCP_HTTP_MODE='true'
$env:MCP_ALLOWED_HOSTS='localhost,127.0.0.1,172.29.176.1'
npx @kajidog/mcp-tts-voicevox

Ou com argumentos de CLI:

npx @kajidog/mcp-tts-voicevox --http --allowed-hosts "localhost,127.0.0.1,172.29.176.1"

3. Configuração do WSL (.mcp.json)

{
  "mcpServers": {
    "tts": {
      "type": "http",
      "url": "http://172.29.176.1:3000/mcp"
    }
  }
}

⚠️ Dentro do WSL, localhost refere-se ao próprio WSL. Use o IP do gateway WSL para acessar o host Windows.

Para usar com o ChatGPT, implante o servidor MCP em modo HTTP na nuvem com acesso a um VOICEVOX Engine.

1. Implantar na Nuvem

Implante com Docker no Render, Railway, etc. (Dockerfile incluído).

2. Configurar o VOICEVOX Engine

Execute o VOICEVOX Engine localmente e exponha-o via ngrok, ou implante-o junto com o servidor MCP.

3. Configurar Variáveis de Ambiente

4. Adicionar Conector no ChatGPT

Vá para Configurações do ChatGPT → Conectores → Adicionar URL do servidor MCP (https://your-app.onrender.com/mcp).

Os passos básicos são os mesmos do ChatGPT, mas o valor de VOICEVOX_PLAYER_DOMAIN é diferente.

O Claude Web exige que ui.domain seja um domínio dedicado baseado em hash. Calcule-o com o seguinte comando:

node -e "console.log(require('crypto').createHash('sha256').update('Your MCP server URL').digest('hex').slice(0,32)+'.claudemcpcontent.com')"

Exemplo: Se a URL do seu servidor MCP é https://your-app.onrender.com/mcp:

node -e "console.log(require('crypto').createHash('sha256').update('https://your-app.onrender.com/mcp').digest('hex').slice(0,32)+'.claudemcpcontent.com')"
# Example output: 48fb73a6...claudemcpcontent.com

Defina esse valor de saída como VOICEVOX_PLAYER_DOMAIN.

Nota: Como o ChatGPT e o Claude Web exigem valores diferentes de VOICEVOX_PLAYER_DOMAIN, uma única instância não pode atender ambos os clientes simultaneamente. Implante instâncias separadas para cada um, ou alterne a variável de ambiente dependendo do cliente alvo.

1. Verifique se o VOICEVOX Engine está em execução

curl http://localhost:50021/speakers

2. Verifique as ferramentas de reprodução específicas da plataforma

• Verifique a instalação do pacote: npm list -g @kajidog/mcp-tts-voicevox
• Verifique a sintaxe JSON no arquivo de configuração
• Reinicie o cliente

Configuração

git clone https://github.com/kajidog/mcp-tts-voicevox.git
cd mcp-tts-voicevox
pnpm install

Comandos

O gerenciador de pacotes é pnpm (npm / yarn não são suportados).

Os servidores de desenvolvimento ficam no pacote do servidor, então execute-os com um filtro: