vv-mcp

Um servidor de texto para fala (TTS) que utiliza o motor VOICEVOX. Requer uma instância do VOICEVOX em execução e atualmente é compatível apenas com macOS.

GitHubExperimente este MCPPatrocinado

Documentação

vv-mcp

Servidor MCP do VOICEVOX - Servidor MCP para usar síntese de voz com Claude Desktop e Claude Code

Requisitos

Node.js 18 ou superior
VOICEVOX instalado e em execução
Sistemas operacionais suportados:
- macOS: use afplay (nenhuma instalação adicional necessária)
- Linux: pw-play (PipeWire) ou paplay (PulseAudio) é necessário
  - Em ambientes PipeWire, use pw-play preferencialmente e, se não estiver disponível, use paplay como fallback
  - PipeWire:
    - Arch Linux: pacman -S pipewire
    - Ubuntu/Debian: apt install pipewire-bin
    - Fedora: dnf install pipewire-utils
  - PulseAudio:
    - Arch Linux: pacman -S pulseaudio
    - Ubuntu/Debian: apt install pulseaudio-utils
    - Fedora: dnf install pulseaudio-utils
- Windows: use PowerShell (nenhuma instalação adicional necessária)

Instalação

Instalar via npm (recomendado)

npm install -g @arrow2nd/vv-mcp

Compilar a partir do código-fonte

git clone https://github.com/arrow2nd/vv-mcp.git
cd vv-mcp
npm install
npm run build

Configuração no Claude Desktop

Edite o arquivo de configuração:

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

Se instalado via npm

{
  "mcpServers": {
    "vv-mcp": {
      "command": "npx",
      "args": ["-y", "@arrow2nd/vv-mcp"],
      "env": {
        "VOICEVOX_URL": "http://localhost:50021",
        "DEFAULT_VOICE_ID": "47",
        "DEFAULT_SPEED": "1.0"
      }
    }
  }
}

Se compilado a partir do código-fonte

{
  "mcpServers": {
    "vv-mcp": {
      "command": "node",
      "args": ["/path/to/vv-mcp/dist/index.js"],
      "env": {
        "VOICEVOX_URL": "http://localhost:50021",
        "DEFAULT_VOICE_ID": "47",
        "DEFAULT_SPEED": "1.0"
      }
    }
  }
}

Configuração no Claude Code

Adicione o seguinte à seção mcpServers de ~/.claude.json:

Ao usar npx/bunx (recomendado)

{
  "mcpServers": {
    "vv-mcp": {
      "command": "npx",
      "args": ["-y", "@arrow2nd/vv-mcp"],
      "env": {
        "VOICEVOX_URL": "http://localhost:50021",
        "DEFAULT_VOICE_ID": "47",
        "DEFAULT_SPEED": "1.0"
      }
    }
  }
}

Se estiver usando bunx, altere para "command": "bunx".

Se compilado a partir do código-fonte

{
  "mcpServers": {
    "vv-mcp": {
      "command": "node",
      "args": ["/path/to/vv-mcp/dist/index.js"],
      "env": {
        "VOICEVOX_URL": "http://localhost:50021",
        "DEFAULT_VOICE_ID": "47",
        "DEFAULT_SPEED": "1.0"
      }
    }
  }
}

Como usar

Após reiniciar o Claude Desktop/Code, as seguintes ferramentas MCP estarão disponíveis:

Ferramentas disponíveis

say - Sintetiza e reproduz texto como fala (execução assíncrona)
list_voices - Obtém a lista de vozes disponíveis
get_queue_status - Verifica o estado da fila de reprodução
clear_queue - Limpa a fila de reprodução
get_voices_in_use - Obtém a lista de IDs de voz atualmente em uso (comum a todos os processos)
get_random_unused_voice - Obtém aleatoriamente uma voz não utilizada
get_session_voice - Obtém a voz a ser usada nesta sessão (fixa por sessão)

Exemplos de uso

「こんにちは」と言って

ナースロボの楽々な声で「完了しました」と言って

利用可能な音声を教えて

Recurso de voz por sessão

Há um recurso que atribui automaticamente uma voz fixa a cada sessão do Claude:

Como usar

# セッション音声を使用して読み上げ
"こんにちは"とセッション音声で言って

Parâmetros da ferramenta say

useSessionVoice: true - Usa a voz da sessão (voiceId é ignorado)
useSessionVoice: false (padrão) - Usa o ID de voz especificado ou a voz padrão

Como funciona

Seleciona automaticamente uma voz no início da sessão
Prioriza vozes que não se sobrepõem a outras sessões
Se todas as vozes estiverem em uso, seleciona a voz menos utilizada
Libera automaticamente a voz ao final da sessão

Suporte a múltiplas instâncias

Quando vários Claude Desktop/Code estão em execução simultaneamente, vozes diferentes são usadas automaticamente para evitar sobreposição de áudio.

Compartilha informações sobre as vozes em uso em cada processo
Seleciona automaticamente vozes não utilizadas com a ferramenta get_random_unused_voice
Cria arquivos de estado no diretório temporário para compartilhar informações

Variáveis de ambiente

Nome da variável	Valor padrão	Descrição
VOICEVOX_URL	http://localhost:50021	URL da API do VOICEVOX
DEFAULT_VOICE_ID	47	ID de voz padrão (ナースロボ＿タイプＴ)
DEFAULT_SPEED	1.0	Velocidade de fala padrão
VV_MCP_STATE_DIR	Diretório temporário do sistema	Diretório para salvar arquivos de estado compartilhados

Licença

MIT