Skip to main content
Glama

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)


Related MCP server: VOICEVOX TTS MCP

🛠 前提条件

  • 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

Available Tools

3 tools
list_speakersA

VOICEVOX Engineで利用可能なスピーカー(キャラクター)の一覧を取得します。

Returns: スピーカー一覧の文字列

Inputs: no named parameters. Returns: result

save_audioA

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

Args: text: 読み上げるテキスト output_path: 保存先のファイルパス(.wav) speaker: スピーカーID(指定しない場合は環境変数SPEAKER_IDの値を使用。list_speakersで一覧を確認できます) speed: 話速 (0.5 〜 2.0, デフォルト: 1.0) pitch: 音高 (-0.15 〜 0.15, デフォルト: 0.0) intonation: 抑揚 (0.0 〜 2.0, デフォルト: 1.0) volume: 音量 (0.0 〜 2.0, デフォルト: 1.0)

Returns: 保存結果のメッセージ

Inputs: text (required), output_path (required), pitch, speed, +3 more. Returns: result

speak_textA

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

Args: text: 読み上げるテキスト speaker: スピーカーID(指定しない場合は環境変数SPEAKER_IDの値を使用。list_speakersで一覧を確認できます) speed: 話速 (0.5 〜 2.0, デフォルト: 1.0) pitch: 音高 (-0.15 〜 0.15, デフォルト: 0.0) intonation: 抑揚 (0.0 〜 2.0, デフォルト: 1.0) volume: 音量 (0.0 〜 2.0, デフォルト: 1.0)

Returns: 再生結果のメッセージ

Inputs: text (required), pitch, speed, volume, +2 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: listing speakers, saving audio to file, and playing audio. No overlap or ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case (list_speakers, save_audio, speak_text), making it predictable.

    Tool Count5/5

    Three tools is well-scoped for a TTS server, covering the essential operations without being too few or too many.

    Completeness4/5

    Core functionality (listing voices, saving, playing) is covered. Missing direct audio data retrieval, but minor gap for a basic server.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      F
      maintenance
      A server that enables Claude 3.7 and other AI agents to access VOICEVOX-compatible speech synthesis engines (AivisSpeech, VOICEVOX, COEIROINK) through the Model Context Protocol.
      1
      12
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      A text-to-speech MCP server that enables AI assistants to speak using the VOICEVOX engine with support for multi-character conversations. It features queue management, low-latency streaming via FFplay, and cross-platform playback across Windows, macOS, and Linux.
      7
      149 npm
      16
      ISC
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables text-to-speech generation and phonetic kana conversion using VOICEROID2 via voiceroid_daemon. It supports customizable voice parameters and provides cross-platform audio playback for synthesized speech.
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A multi-provider voice notification MCP server that enables Claude Code to provide auditory alerts for task completions, confirmation requests, and errors. It supports various TTS engines including VOICEVOX, Google Cloud TTS, and OpenAI for customizable voice feedback.
      8 npm
      1
      MIT