Pronunciation & Voice Coach

mcp-server-pronunciation

精度と安全性に関する注意

このプロジェクトは、ローカルで動作する語学学習用の練習ツールです。バグ、実行時エラー、不正確な文字起こしや発音フィードバック、プラットフォーム固有の録音に関する問題が含まれる場合があります。発音フィードバックはコーチングのための参考情報であり、標準テスト、臨床、雇用、高リスクの評価ではありません。結果を信頼する前に、慎重に確認してください。 DISCLAIMER.md をご覧ください。

MCP（Model Context Protocol）サーバーです。音声で MCP アシスタントに話しかけ、同じターン内で英語の発音、文法、流暢さについてフィードバックを受け取れます。軽いコーチングを交えた気軽な音声チャットに使うことも、特定の文を練習したいときにドリルモードに切り替えることもできます。

Codex CLI、Claude Desktop、Claude Code、Cursor、VS Code、その他の MCP クライアント向けに作られています。すべてローカルで動作します。音声はマイクで録音され、デバイス上の faster-whisper で文字起こしされるため、デバイスの外に送信されることはありません。

mcp-name: io.github.JuhongPark/pronunciation

特長

音声対応の MCP サーバーは、これまで音声を文字入力の代替として扱ってきました。一方、英語学習用の MCP サーバーはテキストのみです。このサーバーはその両方を組み合わせています。自由に話すと、アシスタントが返答し、発音、文法、流暢さに関する発話へのフィードバックが同じツール呼び出し内に表示されます。そのため、アシスタントは自然な返答にフィードバックを織り込むことも、ただの会話ではフィードバックを控えることもできます。

機能

• MCP アシスタントとの音声会話。話すと無音時に自動停止し、アシスタントが文字起こしを読み取って応答します。
• 音素レベルのドリルフィードバック（参照文が指定されている場合）：Needleman-Wunsch による単語アラインメント、単語ごとの予想 IPA と生成 IPA の比較、学習者プロフィールに基づくヒント、ミニマルペア練習、韻律チェック（単語の強勢、文末の上昇イントネーション、節内のポーズ）。
• 拡張可能な学習者プロフィールのサポート：現在のルールパックには、韓国語を第一言語とする学習者の発音パターンに関するヒントと韓国語の解説が含まれています。ほかの第一言語プロフィールへの貢献も歓迎します。
• Whisper のバイアス軽減（任意の [phoneme] 追加機能を使用）：wav2vec2 CTC 強制アラインメントにより、ユーザーが各参照語を実際に発音したかどうかを検証します。そのため、Whisper がより一般的な語に置き換えてしまう珍しい固有名詞や専門用語を、誤発音として提示することがなくなります。
• 会話中の英語フィードバック：発音、文法（よくある不規則動詞の誤り）、流暢さ（話す速さと長いポーズ）。
• 集中的な文の練習に使えるドリルモード（practice、quick_practice、retry）。
• ローカルのみ：Whisper モデルはお使いのマシンで動作し、音声が外部に送信されることはありません。
• クロスプラットフォーム対応：macOS、Linux、Windows、WSL2（録音は自動的に Windows 経由で処理されます）。
• 高速起動：遅延インポートとバックグラウンドでのモデル事前読み込みにより、MCP ハンドシェイクは 1 秒未満で完了します。

要件

• Python 3.11+
• 使用可能なマイク
• デフォルトの Whisper モデル（base.en）用に約 150 MB のディスク容量
• 任意の [phoneme] 追加機能をインストールする場合、強制アラインメント用の wav2vec2 の重みに約 360 MB を追加
• MCP 仕様：公式 Python SDK（mcp>=1.2）経由で 2025-06-18 を対象とします

インストール

安定版リリース

最新の安定版リリースをインストールします。

uvx mcp-server-pronunciation

pip を使用する場合：

pip install mcp-server-pronunciation

このリリースを明示的に指定する場合：

uvx [email protected]

実際のセッションでサーバーを使用する前に、doctor を実行してください。

mcp-server-pronunciation doctor

一般的なインストールコマンド

# Recommended: uvx (no global install, cached between runs)
uvx mcp-server-pronunciation

# Or install as a uv tool
uv tool install mcp-server-pronunciation

# Or pip
pip install mcp-server-pronunciation

# Optional: forced-alignment upgrade for Whisper-bias mitigation + tighter
# phoneme-level feedback. Adds ~200 MB of torch CPU wheels.
pip install 'mcp-server-pronunciation[phoneme]'

Linux：先に PortAudio をインストール

sounddevice は macOS と Windows では PortAudio を wheel に同梱していますが、Linux ではシステムライブラリが必要です。

# Debian / Ubuntu
sudo apt-get install libportaudio2

# Fedora / RHEL
sudo dnf install portaudio

# Arch
sudo pacman -S portaudio

# PipeWire-only systems may also need
sudo apt-get install pipewire-alsa

初回チェック

サーバーを MCP クライアントに接続する前に、事前チェックを実行してください。

uvx mcp-server-pronunciation doctor

任意 — 最初の呼び出しをすぐに実行できるよう、Whisper モデル（約 150 MB）を事前にダウンロードします。

uvx mcp-server-pronunciation pull-model base.en

MCP クライアントに追加する

Codex CLI

codex mcp add pronunciation -- uvx mcp-server-pronunciation

Claude Code

claude mcp add pronunciation -- uvx mcp-server-pronunciation

Claude Desktop

claude_desktop_config.json を編集します：

{
  "mcpServers": {
    "pronunciation": {
      "command": "uvx",
      "args": ["mcp-server-pronunciation"]
    }
  }
}

macOS で Claude Desktop が uvx（spawn uvx ENOENT）を見つけられない場合は、絶対パスを指定してください。ターミナルで which uvx を実行すると確認できます。

Cursor

~/.cursor/mcp.json に追加します：

{
  "mcpServers": {
    "pronunciation": {
      "command": "uvx",
      "args": ["mcp-server-pronunciation"]
    }
  }
}

VS Code（MCP 対応）

.vscode/mcp.json またはユーザー設定に追加します：

{
  "servers": {
    "pronunciation": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-pronunciation"]
    }
  }
}

使用例

1. フィードバック付きの音声チャット

あなた：「音声チャットをしましょう。週末について質問します。converse ツールを使ってください。」

アシスタント（converse を呼び出し）：あなたの発話を録音して文字起こしし、「bought」の代わりに「buyed」と言ったことを記録します

アシスタント：「いいですね。どんなリンゴを買ったのですか？ ちなみに、'buy' の過去形は 'bought' です。ちょっとしたことですが、気づきました。」

2. 特定の文を練習する

あなた：「'th' の音を練習する文をください。」

アシスタント（focus=th を指定して suggest_sentence を呼び出し）：「これを試してください：The three brothers thought thoroughly about their future.」

あなた：「読んでいるところを録音してください。」

アシスタント（その文を参照文として practice を呼び出し）：[phoneme] エクストラがインストールされている場合は、単語ごとの音響的な確信度を含むアラインメント表（match / sub / ins / del）、期待される IPA と実際に発音された IPA の比較による音素レベルの問題、該当する場合は学習者プロファイルに基づくヒント、ミニマルペアのドリル、韻律に関するメモ（単語の強勢、文末の上昇イントネーション、節内のポーズ）を返します。

3. フィードバック後に再挑戦する

あなた：「もう一度やらせてください。」

アシスタント（retry を呼び出し）：同じ目標文を再録音して比較します

ツール

ツール	目的
converse	主要ツール。録音＋文字起こし＋簡単なフィードバック＋アシスタントによるガイダンスで、コーチング付きの自然な音声チャットを実現します。
practice	ドリルモード：ユーザーが特定の参照文を読むところを録音し、詳細な評価を返します。
quick_practice	音素の重点項目と難易度に基づいてランダムな文を選び、練習します。
retry	最後の文を再録音し、新しい試行を前回のものと比較します。
open_voice_panel	クライアントが埋め込み UI に対応している場合、MCP Apps の音声パネルを開きます。
analyze_uploaded_audio	音声パネルからアップロードされた WAV 音声を分析し、最新の音声キャプチャとして保存します。
start_voice_capture	バックグラウンドで録音を開始し、セッション ID をすぐに返します。
voice_capture_status	バックグラウンドキャプチャの状態が録音中、分析中、完了、キャンセル済み、失敗のいずれかを確認します。
wait_for_voice_capture	バックグラウンドキャプチャの完了を待ち、文字起こしとフィードバックを返します。
latest_voice_capture	最新のバックグラウンド音声キャプチャの結果を返します。
cancel_voice_capture	分析開始前にバックグラウンドキャプチャをキャンセル済みにします。
suggest_sentence	録音せずに練習用の文を返します。
record	音声を録音し、WAV ファイルとして保存します（生データ、分析なし）。
assess	最後の録音（または指定された WAV）を、再録音せずに評価します。参照文が指定された場合は、完全なドリル処理（アラインメント、音素の差分、学習者プロファイルに基づくヒント、韻律）を実行します。
check_mic	利用可能な音声入力デバイスを一覧表示します。

音声を評価するツールは、transcript、 clarity_pct、speaking_rate_wpm、top_issue、next_action、 retry_comparison、機械可読形式の完全な assessment、レンダリング済みの report_markdown を含む、構造化された MCP 出力も返します。MCP クライアントは構造化された結果を使って、Markdown を解析せずに再挑戦を提案したり、最も重要な問題を表示したり、より充実した練習 UI を構築したりできます。

音声キャプチャの可視ワークフロー

音声 UI が組み込まれていない MCP クライアントでは、バックグラウンドキャプチャツールを使用して、ユーザーに状況を知らせます。

start_voice_capture(duration=8, mode="conversation")
voice_capture_status(session_id)
wait_for_voice_capture(session_id, timeout=30)
latest_voice_capture()

ステータス応答には、recording、analyzing、done、error、cancelled のいずれかに加え、経過時間、文字起こし、明瞭度、発話速度、フィードバックの Markdown、利用可能な場合は詳細な構造化評価が含まれます。WSL2 では、分析を開始する前に PowerShell の録音が指定時間いっぱいまで待機する場合があるため、duration は短くしてください。

MCP Apps 音声パネル

MCP Apps に対応するクライアントでは、open_voice_panel を呼び出して ui://pronunciation/voice-panel リソースを表示できます。このパネルはブラウザーのマイクアクセスを要求し、ブラウザー内でローカルに録音して、analyze_uploaded_audio 経由で WAV クリップをアップロードし、返された文字起こしとフィードバックを表示します。アップロードする音声は、8～48 kHz のモノラルまたはステレオ音声を含む、読み取り可能な 16 ビット PCM RIFF/WAVE ファイルである必要があります。また、サイズは 20 MB 以下、長さは 120 秒以下にしてください。

アップロードされたクリップは、MCP のみで録音した音声と同じ音声セッションレジストリに保存されます。そのため、パネルの処理完了後にアシスタントは latest_voice_capture を呼び出し、開発メモと発音フィードバックの両方に応答できます。MCP Apps に対応していないクライアントでは、上記の音声キャプチャの可視ワークフローを使用してください。

プロンプトのショートカット

サーバープロンプトを公開する MCP クライアントでは、よく使うワークフローを直接開始できます。

プロンプト	目的
start_voice_chat	軽いフィードバック付きで、ローカルの音声会話を開始します。
daily_practice	提案された文を使った短い練習ループを実行します。
practice_focus	選択した重点項目と難易度に応じたドリルを開始します。
troubleshoot_mic	マイクデバイスと録音設定を確認します。

設定

Whisper モデル

別のモデルサイズを選択するには、MCP_PRONUNCIATION_MODEL を設定します。

# Default — fast, English-only (~150 MB)
export MCP_PRONUNCIATION_MODEL=base.en

# Smaller / faster (~75 MB)
export MCP_PRONUNCIATION_MODEL=tiny.en

# More accurate (~470 MB)
export MCP_PRONUNCIATION_MODEL=small.en

# Multilingual options (larger)
export MCP_PRONUNCIATION_MODEL=small
export MCP_PRONUNCIATION_MODEL=medium

使用可能な値：tiny、tiny.en、base、base.en、small、small.en、medium、medium.en、large-v3、large-v3-turbo。英語のみを使用する場合、同じサイズであれば .en 付きのバリアントのほうが高速で、精度も高くなります。

GPU（CUDA 12 + cuDNN 9）は、利用可能な場合に自動検出されます。それ以外の場合は、int8 量子化を使用して CPU で実行されます。

キャッシュの場所

デフォルトでは、Whisper の重みは ~/.cache/huggingface/hub/ にキャッシュされます。HF_HUB_CACHE で変更できます。

export HF_HUB_CACHE=/path/to/cache

起動時の事前読み込み

デフォルトでは、MCP ハンドシェイクの開始後、サーバーはバックグラウンドで Whisper モデルを事前読み込みします。レジストリの確認、Docker のスモークテスト、その他ツールの検出のみが必要で、モデルのダウンロードを避けたい環境では、MCP_PRONUNCIATION_PRELOAD=0 を設定してください。

export MCP_PRONUNCIATION_PRELOAD=0

一時録音

assess で最後の録音を確認できるよう、録音は一時 WAV ファイルとして書き込まれます。デフォルトでは、サーバープロセスの終了時に削除されます。

export MCP_PRONUNCIATION_AUDIO_RETENTION=session

手動で確認するために一時録音をディスクに残したい場合は、MCP_PRONUNCIATION_AUDIO_RETENTION=keep を設定してください。

マイクと自動停止の制御

デフォルトでは、サーバーはシステムの既定のマイクを使用します。ネイティブの sounddevice 録音は、無音が検出されてから 1.5 秒後に停止します。WSL2 では Windows PowerShell 経由で録音するため、指定時間いっぱいまで待機する場合があります。音声をすばやく確認するには、duration に短い値を指定してください。ネイティブ録音の動作は、次のように変更できます。

# Use a specific input device index or name from the `check_mic` tool
export MCP_PRONUNCIATION_INPUT_DEVICE=1

# Options: low, normal, high
# high helps soft speakers; low is better in noisy rooms
export MCP_PRONUNCIATION_VAD_SENSITIVITY=high

# Seconds of silence before auto-stop, clamped to 0.3-5.0
export MCP_PRONUNCIATION_SILENCE_DURATION=2.0

check_mic を実行すると、既定の入力デバイス、利用可能なデバイスインデックス、アクティブな VAD 設定を確認できます。

MCP クライアントでのモデルの上書き

# Codex CLI
codex mcp add --env MCP_PRONUNCIATION_MODEL=small.en pronunciation -- uvx mcp-server-pronunciation

# Claude Code
claude mcp add pronunciation -e MCP_PRONUNCIATION_MODEL=small.en -- uvx mcp-server-pronunciation

音素分析の追加機能

mcp-server-pronunciation[phoneme] をインストールすると、wav2vec2 ベースの CTC 強制アラインメントが有効になります。Whisper の言語モデルの重み付けデコーダーが書き換えた内容にかかわらず、ユーザーが参照語を実際に発音したかを音響的に判定できるため、珍しい固有名詞や専門用語が誤発音として誤検出されることがなくなります。初回実行時に、約 360 MB の重みが ~/.cache/torch/hub/ にダウンロードされます（TORCH_HOME で変更できます）。デフォルトでは CPU のみで推論し、実行時に int8 に量子化されるため、メモリ使用量は約 95 MB です。

追加機能をインストールしていなくても、強制アラインメントの手順を除くパイプライン全体が assess / practice で実行されます。Whisper の仮説に対する Needleman-Wunsch による単語アラインメント、CMUdict の音素列の差分、学習者プロフィールのヒント、韻律を利用できます。

プラットフォームのサポート

プラットフォーム	録音方式	ステータス
macOS	sounddevice（PortAudio をバンドル）	サポート対象
Linux	sounddevice（libportaudio2 が必要）	サポート対象
Windows	sounddevice（PortAudio をバンドル）	サポート対象
WSL2	PowerShell MCI（winmm.dll）	サポート対象

WSL2 に関する注意：WSLg の PulseAudio は、Windows ホストからマイクの音声を転送しません。このサーバーは WSL2 を自動検出し、代わりに Windows 側の PowerShell を使って録音します。WSL2 での録音では、無音時に自動停止せず、指定した時間いっぱいまで待機することがあります。

トラブルシューティング

まず uvx mcp-server-pronunciation doctor を実行してください

PortAudio、入力デバイス、Whisper モデルのキャッシュ、発音リソース、オプションの強制アラインメント依存関係、空きディスク容量、Python のバージョンを確認できます。何か問題があると感じたら、いつでも実行してください。

Linux で sounddevice のインポートに失敗する

libportaudio2 がありません。上記のインストールセクションを参照してください。インストール後に次を実行します。

uvx mcp-server-pronunciation doctor

音声が録音されない／録音データが空

• macOS：システム設定 → プライバシーとセキュリティ → マイク。Codex CLI、Claude Desktop、Claude Code など、MCP クライアントを起動したアプリにアクセスを許可してください。
• Linux：pavucontrol（PulseAudio）または pw-cli list-objects（PipeWire）で入力レベルを確認してください。PipeWire のみのシステムでは、pipewire-alsa をインストールしてください。
• WSL2：Windows の設定 → サウンド → 入力でマイクをテストしてください。サーバーは WSLg 経由ではなく、Windows 経由で録音します。

初回実行が遅い

Whisper モデルは初回使用時にダウンロードされます（base.en の場合は約 150 MB）。次のコマンドを一度実行して、事前にダウンロードしてください。

uvx mcp-server-pronunciation pull-model base.en

以降の実行では、キャッシュされた重みが再利用されます。それでも起動が遅い場合は、MCP_PRONUNCIATION_MODEL=tiny.en を試してください。

macOS の Claude Desktop：「spawn uvx ENOENT」

Claude Desktop は、~/.local/bin が PATH に含まれていない GUI 専用環境から MCP サーバーを起動します。設定で uvx の絶対パス（/Users/YOU/.local/bin/uvx、または which uvx で表示されるパス）を指定してください。

既知の制限事項

• 安定版パッケージですが、発音と韻律に関するフィードバックは、引き続き実験的なコーチング用の指標です。バグ、実行時エラー、不正確なフィードバック、プラットフォーム固有の録音問題が発生する可能性があります。
• 発音スコアはコーチング用の指標であり、標準テスト、臨床的評価、ネイティブスピーカーとの同等性の判断には使用できません。
• Whisperは、珍しい名前や専門用語、短いクリップ、音量の小さい音声、強いアクセントのある発話を聞き間違えることがあります。オプションの [phoneme] エクストラにより、参照文の誤検出の一部を減らせますが、完全には解消できません。
• 韻律に関するフィードバックはヒューリスティックです。ノイズの多い音声、非常に短い発話、ボーカルフライ、重なり合う発話、途中で切れた録音では、ピッチの追跡が不正確になることがあります。
• 学習者プロファイルのヒントは、意図的にルールベースにしています。現在のパッケージには韓国語を第一言語とする学習者向けのヒントが含まれていますが、誤りを見逃したり、ASRの誤りに過剰反応したりすることがあり、対象を絞った練習の補助として扱う必要があります。ほかの第一言語プロファイルの追加も歓迎します。
• 初回のセットアップ時に、モデルや発音関連のリソースがダウンロードされる場合があります。実際のセッションでサーバーを使用する前に、doctor と pull-model を実行してください。
• 最後の録音を評価できるよう、WAVの一時録音はシステムの一時ディレクトリに保存されます。デフォルトでは、サーバーの終了時に削除されます。後で確認する場合は、MCP_PRONUNCIATION_AUDIO_RETENTION=keep を設定してください。

ベンチマークの状況

このプロジェクトでは、ベンチマークに基づくスコアリングの実現を目指しています。公開ベンチマークに関する今後の作業は ROADMAP.md で管理しており、テスト方法は docs/TESTING.md に、現在のベンチマーク用ヘルパーのドキュメントは docs/BENCHMARKS.md にあります。主な候補は、許容範囲の広い CC BY 4.0 ライセンスと、複数レベルの専門家による発音スコアを備えた Speechocean762 です。L2-ARCTIC は、韓国語を第一言語とする学習者のサブセットのレビューなど、音素の誤りや学習者プロファイルに関する調査に役立ちます。ただし、非商用ライセンスのため、オプションとして扱い、デフォルトのリリースに関する主張とは分けておく必要があります。

公開状況

ソースリポジトリは公開されています。PyPI、GitHub Release、MCP Registry への公開手順は docs/PUBLICATION.md で管理しています。

プライバシー

• すべての音声処理は、お使いのマシン上でローカルに行われます。
• 録音はシステムの一時ディレクトリ（$TMPDIR）に一時的な .wav ファイルとして保存され、MCP_PRONUNCIATION_AUDIO_RETENTION=keep が設定されていない限り、サーバーの終了時に削除されます。
• Whisperモデルはローカルで実行されます。音声データが外部サービスに送信されることはありません。
• オプションの [phoneme] エクストラをインストールすると、wav2vec2 の強制アラインメントもローカルで実行されます。重みは PyTorch Hub から一度だけダウンロードされます。
• テレメトリはありません。アナリティクスもありません。ネットワーク通信は、モデルの重み（Hugging Face からの Whisper、PyTorch Hub からの wav2vec2）の初回ダウンロード以外には行われません。

開発

git clone https://github.com/JuhongPark/mcp-server-pronunciation.git
cd mcp-server-pronunciation
uv sync --extra dev
uv run pytest -v
uv run ruff check .
uv run ruff format --check .

オプションの wav2vec2 強制アラインメントの処理を開発する場合は、phoneme エクストラもインストールしてください。

uv sync --extra dev --extra phoneme

サポート

課題の報告先：https://github.com/JuhongPark/mcp-server-pronunciation/issues

ライセンス

MIT。LICENSE を参照してください。

サードパーティ製コンポーネント（すべて MIT または許容範囲の広いライセンス）：

• faster-whisper — MIT
• OpenAI Whisper models — MIT
• CTranslate2 — MIT
• sounddevice — MIT
• PortAudio — MIT
• cmudict — BSD
• g2p-en — Apache 2.0
• librosa — ISC
• オプション（[phoneme] エクストラ）：PyTorch — BSD、torchaudio — BSD、wav2vec2 weights — MIT