voice-dialog

AI Agentに音声対話機能を追加するMCP server。コマンドラインツールとしても使えます。Agentが作業を終えたら音声で知らせたり、質問を投げかけたり、あなたの回答を聞き取ったりできます。認識はローカルのwhisperで実行し、合成はシステム標準のTTSを使用します。完全にオフラインで動作し、音声を送信しません。

できること

你（没看屏幕）："搞定了吗？"
Agent（出声）："代码写完了，测试全过。要提交吗？"      ← ask_by_voice
你："先不提交，我看看再说"                             ← listen 收到，本地转写
Agent（出声）："好，先留着。"                          ← speak

Related MCP server: Pipecat MCP Server

クイックスタート

git clone https://github.com/VictorHuang0843/voice-dialog.git
cd voice-dialog

# 没装 uv？先来这个（Windows 用 install.ps1）：
#   curl -LsSf https://astral.sh/uv/install.sh | sh

uv run voice-dialog init

init は7ステップの全自動ガイドです：uvのインストール → 依存関係のインストール（uvがPythonもインストールしてくれます）→ whisperモデルのダウンロード（464MB、中国のネットワークでは自動的にhf-mirrorを使用）→ マイク権限の実地テスト → TTS音声出力の実地テスト → MCP登録コマンドの表示。失敗したステップがあれば、そのステップの修復コマンドが表示され、修正して再実行するだけです。

試しに：

uv run voice-dialog speak "语音系统就绪" --lang zh
uv run voice-dialog ask "请说话" --wait-start 60
# 你会听到：高亮上扬"叮↑"= 开始说话 → 停 3 秒 → 低沉"咚…咚↓"= 录音结束

あなたのAgentに接続する

任意のMCPクライアント（Claude Code、Codex、Cursor、LoopX……）：

{
  "mcpServers": {
    "voice-dialog": {
      "command": "uv",
      "args": ["--project", "/你的路径/voice-dialog", "run", "voice-dialog", "serve"]
    }
  }
}

Claude Codeの一行登録：

claude mcp add voice-dialog -s user -- uv --project /你的路径/voice-dialog run voice-dialog serve

MCP非対応のツール：CLIを直接呼び出し、uv run voice-dialog speak/listen/ask "..."。

Claude Code Skill（オプション、Agentにいつ話すか/いつ聞くかを教える）：skills/voice-dialog/ を ~/.claude/skills/ にコピーします。

対応プラットフォーム

言語は自動検出（whisperは約100言語に対応）、VD_LANG=zh で固定可能；モデルサイズは VD_MODEL=small で調整可能。

よくある質問

プライバシー

音声はローカルで認識（faster-whisper）、テキストはシステムTTSで再生、クラウドAPIは一切呼び出さず、音声をアップロードしません。

ライセンス

MIT

モデルについて

デフォルトでダウンロードされるものは？ whisper small（int8量子化、約464MB）。中英語の認識精度と速度のバランスが取れたモデルです。初回の listen/init 時に自動ダウンロードされ、以降はローカルにキャッシュされます（macOS/Linux：~/.cache/huggingface/hub/、Windows：%USERPROFILE%\.cache\huggingface\hub\）。再ダウンロードは発生しません。

ダウンロード元の選択方法は？ コードにはダウンロードロジックはハードコードされていません——WhisperModel("small", ...) の構築時にfaster-whisperライブラリがHuggingFaceから自動的にダウンロードします。デフォルトは公式ソースhuggingface.co；公式ソースに接続できない場合は、コードが自動的に国内ミラーhf-mirror.comに切り替えて再試行します（HF_ENDPOINT 環境変数の設定で実装）。国内ユーザーは事前に手動で固定することもできます：

export HF_ENDPOINT=https://hf-mirror.com   # 加进 ~/.zshrc 一劳永逸

より大きなモデルに変更？ 環境変数 VD_MODEL で制御し、再起動で有効です：

VD_MODEL=base uv run voice-dialog listen   # 单次用 base

zipからのインストール（git clone不要）

zipをダウンロード（または友人から直接受け取る）→ 好きな場所に解凍、例えば ~/tools/ → ターミナルを開いてディレクトリに入り、あとはAIに任せます：

Claude Code（またはコマンドを実行できるAIプログラミングツール）で、以下の内容をそのまま送信します：

帮我安装这个目录里的 voice-dialog 项目：
1. cd 到这个目录跑 uv run voice-dialog init（没装 uv 就先装：curl -LsSf https://astral.sh/uv/install.sh | sh）
2. init 全绿后，把打印出来的 claude mcp add 命令执行掉
3. 最后跑 uv run voice-dialog doctor 给我看结果

すべてをインストールしてClaude Codeに登録し、セッションを再起動すれば使えます。

手動でも可能です。たった2つのコマンドです：

cd 解压后的目录
uv run voice-dialog init        # 结束时打印注册命令，复制执行

Macでターミナルに不慣れな場合：解凍後、フォルダを右クリック → サービス → フォルダ位置で新しいターミナルウィンドウを開く、でディレクトリに移動できます。