voice-dialog

Ein MCP-Server, der KI-Agenten Sprachdialog-Fähigkeiten verleiht – und auch als Kommandozeilen-Tool verwendet werden kann. Wenn der Agent seine Arbeit erledigt hat, kann er es dir mündlich mitteilen; er kann aber auch eine Frage stellen und deine Antwort anhören. Die Erkennung läuft lokal über whisper, die Synthese nutzt die systemeigene TTS – durchgehend ohne Internetverbindung und ohne Audio-Übertragung.

Was es kann

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

Related MCP server: Pipecat MCP Server

Schnellstart

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 ist eine 7-stufige, vollautomatische Anleitung: uv installieren → Abhängigkeiten installieren (uv installiert sogar Python für dich) → Whisper-Modell herunterladen (464 MB, läuft in chinesischen Netzwerken automatisch über hf-mirror) → Mikrofonberechtigung per Praxistest prüfen → TTS-Ausgabe per Praxistest prüfen → MCP-Registrierungsbefehl ausgeben. Schlägt ein Schritt fehl, wird der Reparaturbefehl für genau diesen Schritt angezeigt; nach der Reparatur einfach erneut ausführen.

Probier einen Satz aus:

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

Agent-Anbindung

Beliebige MCP-Clients (Claude Code, Codex, Cursor, LoopX …):

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

Claude Code: Registrierung mit einer Zeile:

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

Tools ohne MCP-Unterstützung: CLI direkt aufrufen, uv run voice-dialog speak/listen/ask "...".

Claude Code Skill (optional, bringt dem Agenten bei, wann er sprechen und wann er zuhören soll): skills/voice-dialog/ nach ~/.claude/skills/ kopieren.

Unterstützte Plattformen

Die Sprache wird automatisch erkannt (whisper unterstützt ~100 Sprachen); mit VD_LANG=zh lässt sie sich festlegen; die Modellgröße lässt sich über VD_MODEL=small anpassen.

Häufige Probleme

Datenschutz

Sprache wird lokal erkannt (faster-whisper), Text wird über die systemeigene TTS wiedergegeben. Es werden keine Cloud-APIs aufgerufen und keine Audiodaten hochgeladen.

Lizenz

MIT

Hinweise zum Modell

Was wird standardmäßig heruntergeladen? whisper small (int8-quantisiert, ca. 464 MB) – das ausgewogene Verhältnis zwischen Erkennungsqualität und -geschwindigkeit bei Chinesisch und Englisch. Beim ersten listen/init wird es automatisch heruntergeladen und danach lokal zwischengespeichert (macOS/Linux: ~/.cache/huggingface/hub/, Windows: %USERPROFILE%\.cache\huggingface\hub\); anschließend wird es nie wieder heruntergeladen.

Wie wird die Download-Quelle gewählt? Die Download-Logik ist nicht fest im Code verankert – beim Erzeugen von WhisperModel("small", ...) lädt die Bibliothek faster-whisper das Modell automatisch von HuggingFace herunter. Standardmäßig wird die offizielle Quelle huggingface.co verwendet; ist sie nicht erreichbar, wechselt der Code automatisch zum chinesischen Mirror hf-mirror.com und versucht es erneut (umgesetzt durch Setzen der Umgebungsvariable HF_ENDPOINT). Auch chinesische Nutzer können sie vorab manuell festlegen:

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

Auf ein größeres Modell wechseln? Die Umgebungsvariable VD_MODEL steuert die Auswahl; sie wird beim erneuten Ausführen wirksam:

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

Installation aus der Zip (ohne git clone)

Zip herunterladen (oder ein Freund schickt sie dir direkt) → an den gewünschten Ort entpacken, z. B. ~/tools/ → Terminal öffnen, in den Ordner wechseln – den Rest erledigt die KI:

帮我安装这个目录里的 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 给我看结果

Sie installiert alles und registriert es in Claude Code; nach einem Neustart der Sitzung ist es einsatzbereit.

Es geht auch manuell, mit nur zwei Befehlen:

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

Wer sich auf dem Mac mit dem Terminal nicht auskennt: Nach dem Entpacken Rechtsklick auf den Ordner → Dienste → „Neues Terminalfenster im Ordner“ – schon ist man im Verzeichnis.