livechat-mcp

AIコーディングアシスタントと継続的な音声会話ができるModel Context Protocol (MCP) サーバーです。あなたが話すと、その音声がWhisperでローカルに文字起こしされ、各発話がまるでタイピングしたかのようにアシスタントに送信されます。タブの切り替え、コピー＆ペースト、バッチ録音は不要です。

あらゆるMCPホストで動作します。以下のホストを公式サポートしています：

• Claude Code

• Codex CLI

• Gemini CLI

要件

• macOS、Linux、またはWindows (PowerShell経由、またはWSL2 / Git Bash環境)。

• Python 3.10以上

• インストール済みのMCPホスト (Claude Code, Codex, Geminiなど)

• 動作するマイク

• Whisperモデルキャッシュと依存関係用に約500MBのディスク容量

• プロジェクト管理用に uv (推奨)

クイックインストール (推奨)

リポジトリをクローンした後：

# macOS / Linux / Git Bash on Windows
./install.sh

# Native Windows PowerShell
.\install.ps1

ブートストラップがOSを検出し、必要に応じてportaudioをインストールし (brew / apt / dnf / pacman / zypper — Windowsのwheelには同梱されています)、uvがなければインストールし、uv syncを実行し、ウィザードを ~/.local/bin に配置して、対話型セットアップウィザードを起動します。

Windows: ネイティブのロックには msvcrt を使用し、テイクオーバーのシグナル伝達はファイルベースで行われるため、fcntl への依存はありません。対話型ウィザードはbashスクリプトです — install.ps1 はGit Bashを通じてこれを呼び出します。Git Bashがない場合は winget でインストールを提案します。

手動セットアップ

ステップバイステップでインストールしたい場合は、install.sh が行う内容は以下の通りです：

1. portaudioのインストール

sounddevice には portaudio が必要です。

• macOS: brew install portaudio

• Debian/Ubuntu: sudo apt-get install libportaudio2 portaudio19-dev

• Fedora/RHEL: sudo dnf install portaudio portaudio-devel

• Arch: sudo pacman -S portaudio

2. uv がない場合はインストール

curl -LsSf https://astral.sh/uv/install.sh | sh

3. クローンと依存関係のインストール

cd livechat-mcp
uv sync

これにより .venv/ が作成され、mcp、faster-whisper、sounddevice、silero-vad、torch などがインストールされます。

4. セットアップウィザードの実行

install -m 0755 bin/livechat-mcp ~/.local/bin/livechat-mcp
livechat-mcp setup

ウィザードは以下のことを行います：

1. どのインストール先のアシスタント（Claude Code / Codex / Gemini、またはその組み合わせ）かを確認します。

2. カスタムスラッシュコマンドをサポートするホストに /livechat および /endlivechat スラッシュコマンドをコピーします。Codexの場合、現在のCodex CLIリリースではカスタムプロンプトが /livechat として公開されていないため、レガシープロンプトファイルと livechat スキルの両方をインストールします。

3. 各ホストの設定ファイルにMCPサーバーを登録します。

4. 調整可能な環境変数（無音しきい値、Whisperモデルなど）を案内します — デフォルトのままにする場合はEnterを押してください。

~/.local/bin が PATH に含まれていることを確認してください（公式の uv インストーラーを使用した場合は既に含まれています）。

手動で設定したい場合は、各ホストの手順を以下に示します。

5. マイク権限の付与

• macOS: サーバーが初めてオーディオをキャプチャしようとすると、macOSはターミナルアプリ（Terminal, iTerm, Ghostty, Warpなど）に対してマイクへのアクセスを求めます。プロンプトを見逃した場合は、手動で有効にしてください：

  システム設定 → プライバシーとセキュリティ → マイク → ターミナルアプリを有効にする

  これをスキップすると、オーディオキャプチャは無音を返し、何も文字起こしされません。

• Windows: 設定 → プライバシーとセキュリティ → マイク → デスクトップアプリによるマイクへのアクセスを許可する（ターミナルに許可が与えられていることを確認してください）。

• Linux: 通常プロンプトは表示されません — ユーザーが適切なALSA / PulseAudio / Pipewireアクセス権（通常は audio グループ）を持っていることを確認してください。

6. Whisperモデルの事前ダウンロード (オプション)

初回実行時に base.en (約150MB) がダウンロードされます。事前にダウンロードしておくことも可能です：

uv run python -c "from faster_whisper import WhisperModel; WhisperModel('base.en', device='cpu', compute_type='int8')"

手動インストール (livechat-mcp setup を使用した場合はスキップ)

Claude Code

スラッシュコマンドをコピーします：

mkdir -p ~/.claude/commands
cp commands/livechat.md ~/.claude/commands/
cp commands/endlivechat.md ~/.claude/commands/

MCPサーバーを登録します：

claude mcp add livechat -- uv --directory "$(pwd)" run livechat-mcp

または ~/.claude.json を直接編集します：

{
  "mcpServers": {
    "livechat": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/livechat-mcp", "run", "livechat-mcp"]
    }
  }
}

Codex CLI

Codexスキルとレガシープロンプトファイルをインストールします：

mkdir -p ~/.codex/skills/livechat
cp skills/livechat/SKILL.md ~/.codex/skills/livechat/
mkdir -p ~/.codex/prompts
cp commands/livechat.md ~/.codex/prompts/
cp commands/endlivechat.md ~/.codex/prompts/

~/.codex/config.toml にMCPサーバーを登録します：

[mcp_servers.livechat]
command = "uv"
args = ["--directory", "/absolute/path/to/livechat-mcp", "run", "livechat-mcp"]

Gemini CLI

GeminiはカスタムコマンドにTOMLを使用します。ウィザードがこれらを生成しますが、手動で行う場合は commands/gemini/livechat.toml.template を参照してください（livechat-mcp setup を一度実行すると作成されます）。

~/.gemini/settings.json にMCPサーバーを登録します：

{
  "mcpServers": {
    "livechat": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/livechat-mcp", "run", "livechat-mcp"]
    }
  }
}

使用方法

任意のターミナルでアシスタントのCLIを開きます：

claude    # or: codex    or: gemini

次に、アシスタントのプロンプトで以下を入力します：

/livechat            # Claude Code, Gemini CLI
use livechat         # Codex CLI

Codexの再起動が必要です。 Codexは起動時にのみスキルとMCPサーバーを読み込みます。Codexが開いている間にウィザードを実行した場合は、use livechat を使用する前に終了して再起動してください。

Codex 0.128.0はユーザー定義の /livechat スラッシュコマンドをサポートしていません。/ は現在Codexの組み込みコマンド用に予約されています。セットアップでは代わりに検出可能な livechat スキルがインストールされるため、use livechat と入力するか、/skills を開いて livechat を選択できます。

アシスタントが get_voice_input を呼び出し、聞き取りを開始します。通常通り話してください。 約1.5秒間停止すると、発話が確定し、文字起こしされてプロンプトとして送信されます。アシスタントが応答し、その後すぐに次の発話を聞き取ります。

アシスタントが応答を生成している間もマイクはアクティブです。その間に話した内容はキューに入れられ、次の get_voice_input 呼び出し時にまとめて配信されます。

セッションの終了

3つの方法があります：

1. /endlivechat — 最もクリーンな方法で、アシスタントのプロンプトから実行します。（応答の途中である場合は、まず現在のターンを中断する必要があります。）

2. ウェイクフレーズ — terminate voice session now と言います。文字起こしがシャットダウンをトリガーします。このフレーズは、実際のレビュー内容との衝突を避けるために意図的に不自然なものにしています。LIVECHAT_END_PHRASE で設定可能です。

3. Ctrl+C — MCPサーバーを強制終了します。アシスタントは次の呼び出しでツールエラーを確認し、ループを停止します。

設定

すべての調整可能な項目は livechat_mcp/config.py にあり、環境変数で上書きできます：

設定を簡単に行うには livechat-mcp set KEY VALUE を使用します。これは見つかったすべてのホスト設定（Claude / Codex / Gemini）の env ブロックを編集します。

livechat-mcp show           # print current env block(s)
livechat-mcp set LIVECHAT_SILENCE_SEC 1.5
livechat-mcp unset LIVECHAT_DEBUG

変更後はアシスタントのCLIを再起動してください。MCPの環境変数はサーバー起動時に読み込まれます。

手動で行う場合は、各ホストの設定にあるlivechat MCPエントリの env フィールドを編集してください。Claude Codeの例：

{
  "mcpServers": {
    "livechat": {
      "command": "uv",
      "args": ["--directory", "/abs/path", "run", "livechat-mcp"],
      "env": {
        "LIVECHAT_WHISPER_MODEL": "small.en",
        "LIVECHAT_DEBUG": "1"
      }
    }
  }
}

トラブルシューティング

話しても何も起こらない。 以下の順序で確認してください：ターミナルアプリのマイク権限、マイク入力レベル（システム設定 → サウンド）、LIVECHAT_DEBUG=1 を設定してstderrでVADイベントを確認、LIVECHAT_VAD_THRESHOLD を 0.3 に下げる。

文字起こしが不正確。 モデルをアップグレードしてください：LIVECHAT_WHISPER_MODEL=small.en または medium.en。medium.en はCPUでは顕著に遅くなりますが（それでもリアルタイムに近い）、技術用語にははるかに適しています。

発話がすぐに終了する / 終了するのが遅すぎる。 LIVECHAT_SILENCE_SEC を調整してください（または livechat-mcp set LIVECHAT_SILENCE_SEC 1.5 を実行）。1.0〜4.5が有効な範囲です。低くすると反応が速く感じられますが、思考中の休止で途切れるリスクがあります。

uv が見つからない。 uvをインストールする（推奨）か、MCP設定の command を、アクティブ化されたvenv内からの python -m livechat_mcp.server の直接呼び出しに変更してください。

サーバーは起動するが、アシスタントがツールを呼び出さない。 /livechat が呼び出されたことを確認してください。スラッシュコマンドがないと、アシスタントはループに入る指示を受け取りません。

サーバーログがアシスタントのUIにゴミとして表示される / プロトコルを壊す。 これは発生しないはずです。すべてのサーバーログはstderrに送信されます。もし表示される場合はバグを報告してください。file=sys.stderr を指定せずに print(...) 文を追加していないことを確認してください。

起動時に portaudio エラーが発生する。 インストールしてください：brew install portaudio。インストール済みでも失敗する場合は brew reinstall portaudio を試し、sounddeviceを再インストールしてください：uv sync --reinstall。

仕組み（要約）

[mic] → [Silero VAD] → [Whisper] → [queue] ← [get_voice_input tool] ← [Assistant]
   ↑________background thread, always running________↑

オーディオパイプラインはMCPツールから切り離されているため、サーバーが起動している間はマイクが常にアクティブです。アシスタントが応答を生成している間に話された発話はキューに入れられ、次のツール呼び出し時に配信されます。

ライセンス

MIT。