mcp-voicevox-server-python

Claude Code の返答を VOICEVOX で読み上げるための MCP (Model Context Protocol) サーバーです。 日本語の自然な合成音声により、開発中のフィードバックを耳で受け取ることが可能になります。

---

🚀 概要

このプロジェクトは、Claude Code からの指示を受け取り、Docker 上で動作する VOICEVOX Engine を介して音声を生成、ローカルの ffplay で再生します。

システム構成

• Client: Claude Code
• MCP Server: Python (FastMCP)
• Engine: VOICEVOX Engine (Docker)
• Player: ffplay (FFmpeg)

---

🛠 前提条件

• Python: 3.10 以上
• uv: パッケージマネージャー（推奨）
• Docker: VOICEVOX Engine の実行に必要
• FFmpeg: 音声再生用の ffplay コマンドを使用
  • macOS: brew install ffmpeg
  • Windows: choco install ffmpeg / scoop install ffmpeg
  • Linux: sudo apt install ffmpeg

---

📦 セットアップ

1. 依存関係のインストール

uv を使用する場合（推奨）

uv sync

pip を使用する場合

pip install -r requirements.txt

---

⚙️ Claude Code 設定

~/.claude.json に以下の設定を追加します。

uv を使用する場合（推奨）

{
  "mcpServers": {
    "voicevox": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-voicevox-server", "python", "server.py"],
      "env": {
        "VOICEVOX_URL": "http://localhost:50021",
        "SPEAKER_ID": "3"
      }
    }
  }
}

python を直接使用する場合

{
  "mcpServers": {
    "voicevox": {
      "command": "python3",
      "args": ["/path/to/mcp-voicevox-server/server.py"],
      "env": {
        "VOICEVOX_URL": "http://localhost:50021",
        "SPEAKER_ID": "3"
      }
    }
  }
}

環境変数

変数名	説明	デフォルト
VOICEVOX_URL	Engine のアドレス	http://localhost:50021
SPEAKER_ID	キャラクターID	3
AUTO_START_ENGINE	自動的にDockerを起動するか	true

キャラクター一覧（一部）

ID	キャラクター
2	四国めたん
3	ずんだもん
8	春日部つむぎ

---

🐳 VOICEVOX Engine の自動起動

MCP サーバー起動時に VOICEVOX Engine が動作していない場合、自動的に Docker で起動します。

仕組み

1. サーバー起動時に VOICEVOX_URL への接続をチェック
2. 接続できない場合、docker compose up -d を実行
3. Engine が起動するまで最大30秒待機

手動で起動する場合

自動起動を無効にしたい場合は、環境変数を設定してください：

{
  "env": {
    "AUTO_START_ENGINE": "false"
  }
}

手動で Docker を起動する場合：

# docker compose を使用
docker compose up -d

# または直接実行
docker run --rm -d -p 50021:50021 voicevox/voicevox_engine:cpu-ubuntu20.04-latest

---

🛠 提供されるツール

speak_text

テキストを VOICEVOX で音声合成し、スピーカーから再生します。

引数:

• text (string, 必須): 読み上げるテキスト
• speed (number, optional): 話速 (0.5 〜 2.0, デフォルト: 1.0)
• pitch (number, optional): 音高 (-0.15 〜 0.15, デフォルト: 0.0)
• intonation (number, optional): 抑揚 (0.0 〜 2.0, デフォルト: 1.0)
• volume (number, optional): 音量 (0.0 〜 2.0, デフォルト: 1.0)

戻り値:

• 再生完了メッセージまたはエラーメッセージ

save_audio

テキストを VOICEVOX で音声合成し、WAV ファイルとして保存します。

引数:

• text (string, 必須): 読み上げるテキスト
• output_path (string, 必須): 保存先のファイルパス（.wav）
• speed (number, optional): 話速 (0.5 〜 2.0, デフォルト: 1.0)
• pitch (number, optional): 音高 (-0.15 〜 0.15, デフォルト: 0.0)
• intonation (number, optional): 抑揚 (0.0 〜 2.0, デフォルト: 1.0)
• volume (number, optional): 音量 (0.0 〜 2.0, デフォルト: 1.0)

戻り値:

• 保存完了メッセージまたはエラーメッセージ

---

💡 使い方

Claude Code 上で直接指示してください。

「今のコード変更の概要を speak_text で教えて」
「テストが通ったら『お疲れ様なのだ』と喋って」

自動化のヒント

.claude/settings.json や CLAUDE.md に以下のようなシステムプロンプトを追加すると便利です：

各回答の最後には必ず speak_text ツールを使用して、回答の重要なポイントを1文で読み上げてください。

---

📝 ライセンス

MIT