vv-mcp

vv-mcp

Servidor MCP de VOICEVOX: servidor MCP para usar síntesis de voz con Claude Desktop y Claude Code

Requisitos

• Node.js 18 o superior
• VOICEVOX instalado y en ejecución
• Sistemas operativos compatibles:
  • macOS: usa afplay (no requiere instalación adicional)
  • Linux: requiere pw-play (PipeWire) o paplay (PulseAudio)
    • En entornos PipeWire, usa pw-play de forma prioritaria y recurre a paplay si no está disponible
    • 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: usa PowerShell (no requiere instalación adicional)

Instalación

Instalar desde npm (recomendado)

npm install -g @arrow2nd/vv-mcp

Compilar desde el código fuente

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

Configuración en Claude Desktop

Edita el archivo de configuración:

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

Si se instaló con 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"
      }
    }
  }
}

Si se compiló desde el código fuente

{
  "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"
      }
    }
  }
}

Configuración en Claude Code

Agrega lo siguiente a la sección mcpServers de ~/.claude.json:

Al 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"
      }
    }
  }
}

Si usas bunx, cámbialo a "command": "bunx".

Si se compiló desde el código fuente

{
  "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"
      }
    }
  }
}

Uso

Después de reiniciar Claude Desktop/Code, estarán disponibles las siguientes herramientas MCP:

Herramientas disponibles

• say: sintetiza texto a voz y lo reproduce (ejecución asíncrona)
• list_voices: obtiene la lista de voces disponibles
• get_queue_status: verifica el estado de la cola de reproducción
• clear_queue: limpia la cola de reproducción
• get_voices_in_use: obtiene la lista de IDs de voz actualmente en uso (común a todos los procesos)
• get_random_unused_voice: obtiene una voz no utilizada al azar
• get_session_voice: obtiene la voz que se usará en esta sesión (fija por sesión)

Ejemplos de uso

「こんにちは」と言って

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

利用可能な音声を教えて

Función de voz de sesión

Existe una función que asigna automáticamente una voz fija a cada sesión de Claude:

Cómo usarla

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

Parámetros de la herramienta say

• useSessionVoice: true: usa la voz de la sesión (se ignora voiceId)
• useSessionVoice: false (predeterminado): usa el ID de voz especificado o la voz predeterminada

Cómo funciona

• Selecciona automáticamente una voz al inicio de la sesión
• Prioriza la selección de una voz que no se superponga con otras sesiones
• Si todas las voces están en uso, selecciona la voz menos utilizada
• Libera automáticamente la voz al finalizar la sesión

Compatibilidad con múltiples instancias

Cuando varias instancias de Claude Desktop/Code se ejecutan simultáneamente, se usan automáticamente voces diferentes para evitar la duplicación de voces.

• Comparte la información de las voces en uso entre procesos
• La herramienta get_random_unused_voice selecciona automáticamente una voz no utilizada
• Crea archivos de estado en un directorio temporal para compartir información

Variables de entorno

Variable	Valor predeterminado	Descripción
VOICEVOX_URL	http://localhost:50021	URL de la API de VOICEVOX
DEFAULT_VOICE_ID	47	ID de voz predeterminado (ナースロボ＿タイプＴ)
DEFAULT_SPEED	1.0	Velocidad de habla predeterminada
VV_MCP_STATE_DIR	Directorio temporal del sistema	Directorio para guardar archivos de estado compartidos

Licencia

MIT