Skip to main content
Glama

voice-dialog

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

できること

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

ツール

用途

speak

一方向の読み上げ(タスク完了、マイルストーン)

listen

録音+認識(あなたの口述指示)

ask_by_voice

原子的な問答:一言→一回聞く、自動で聞き続けることは絶対にない(無限ループ防止)

init

ワンクリック初期化(下記参照)

doctor

環境診断(確認のみ、インストールしない)

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/ にコピーします。

対応プラットフォーム

macOS

Windows

Linux

音声認識

実測済み

利用可能

利用可能

音声合成

システムTTS

SAPI

espeak-ngのインストールが必要

プロンプト音

利用可能

利用可能

ffmpegが必要

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

よくある質問

症状

解決策

initがuv未インストールと報告

上記のcurlインストールコマンドを実行し、インストール後にターミナルを再起動

マイクプローブに失敗

macOS:システム設定→プライバシーとセキュリティ→マイク→使用するターミナルをチェック;Windows:設定→プライバシー→マイク

モデルのダウンロード失敗/極端に遅い

export HF_ENDPOINT=https://hf-mirror.com を実行してから再実行

TTSが無音

システムの出力デバイスが仮想サウンドカード(BlackHoleなど)に乗っ取られていないか確認

コードを変更しても反映されない

MCP serverは常駐プロセス:pkill -f "voice-dialog serve"

プライバシー

音声はローカルで認識(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

サイズ

特徴

tiny

~75MB

最速、精度は普通

base

~142MB

速い、日常用途には十分

small(デフォルト)

~464MB

バランスが良く、推奨

medium

~1.5GB

より正確、Mチップでは秒級の書き起こしが十秒級に

large-v3

~3GB

最も正確で最も遅い、短い会話には推奨しない

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

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers