vv-mcp

VOICEVOX MCP Server - Claude DesktopとClaude Codeで音声合成を利用するためのMCPサーバー

必要要件

• Node.js 18以上
• VOICEVOXがインストールされ、起動していること
• サポートOS:
  • macOS: afplayを使用（追加インストール不要）
  • Linux: pw-play（PipeWire）または paplay（PulseAudio）が必要
    • PipeWire環境では pw-play を優先的に使用し、なければ paplay にフォールバック
    • 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: PowerShellを使用（追加インストール不要）

インストール

npmからインストール（推奨）

npm install -g @arrow2nd/vv-mcp

ソースからビルド

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

Claude Desktopでの設定

設定ファイルを編集：

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

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

ソースからビルドした場合

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

Claude Codeでの設定

~/.claude.jsonのmcpServersセクションに以下を追加：

npx/bunxを使用する場合（推奨）

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

bunxを使用する場合は"command": "bunx"に変更してください。

ソースからビルドした場合

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

使用方法

Claude Desktop/Codeを再起動後、以下のMCPツールが利用可能になります：

利用可能なツール

• say - テキストを音声合成して再生（非同期実行）
• list_voices - 利用可能な音声一覧を取得
• get_queue_status - 再生キューの状態を確認
• clear_queue - 再生キューをクリア
• get_voices_in_use - 現在使用中の音声IDのリストを取得（全プロセス共通）
• get_random_unused_voice - 使用されていない音声をランダムに1つ取得
• get_session_voice - このセッションで使用する音声を取得（セッション毎に固定）

使用例

「こんにちは」と言って

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

利用可能な音声を教えて

セッション音声機能

各Claudeセッションに固定の音声を自動割り当てする機能があります：

使用方法

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

sayツールのパラメータ

• useSessionVoice: true - セッション音声を使用（voiceIdは無視される）
• useSessionVoice: false（デフォルト） - 指定した音声IDまたはデフォルト音声を使用

仕組み

• セッション開始時に自動的に音声を選択
• 他のセッションと重複しない音声を優先的に選択
• 全音声が使用中の場合は使用頻度の低い音声を選択
• セッション終了時に自動的に音声を解放

複数インスタンス対応

複数のClaude Desktop/Codeが同時に動作している場合、自動的に異なる音声を使用して音声の重複を避けます。

• 各プロセスで使用中の音声情報を共有
• get_random_unused_voiceツールで未使用の音声を自動選択
• 一時ディレクトリに状態ファイルを作成して情報を共有

環境変数

| 変数名 | デフォルト値 | 説明 | | ---------------- | ------------------------ | ----------------------------------------- | | VOICEVOX_URL | http://localhost:50021 | VOICEVOX APIのURL | | DEFAULT_VOICE_ID | 47 | デフォルトの音声ID (ナースロボ＿タイプＴ) | | DEFAULT_SPEED | 1.0 | デフォルトの話速 | | VV_MCP_STATE_DIR | システム一時ディレクトリ | 共有状態ファイルの保存ディレクトリ |

ライセンス

MIT