vv-mcp
VOICEVOX MCP Server - Claude DesktopとClaude Codeで音声合成を利用するためのMCPサーバー
必要要件
- Node.js 18以上
- VOICEVOXがインストールされ、起動していること
- サポートOS:
- macOS:
afplayを使用（追加インストール不要） - Linux:
paplay（PulseAudio）が必要- Arch Linux:
pacman -S pulseaudio - Ubuntu/Debian:
apt install pulseaudio-utils - Fedora:
dnf install pulseaudio-utils
- Arch Linux:
- macOS:
インストール
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
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