Skip to main content
Glama

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

Werkzeug

Zweck

speak

Einseitige Ansage (Aufgabe erledigt, Meilenstein)

listen

Aufnahme + Erkennung (du diktierst Anweisungen)

ask_by_voice

Atomare Frage-Antwort: eine Ansage → einmal zuhören, niemals automatisch weiter zuhören (verhindert Endlosschleifen)

init

Ein-Klick-Initialisierung (siehe unten)

doctor

Umgebungs-Check (prüft nur, installiert nichts)

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

macOS

Windows

Linux

Spracherkennung

getestet

nutzbar

nutzbar

Sprachsynthese

System-TTS

SAPI

erfordert espeak-ng

Signaltöne

nutzbar

nutzbar

erfordert ffmpeg

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

Symptom

Lösung

init meldet, dass uv nicht installiert ist

Den curl-Installationsbefehl von oben ausführen, danach das Terminal neu öffnen

Mikrofontest schlägt fehl

macOS: Systemeinstellungen → Datenschutz & Sicherheit → Mikrofon → dein Terminal aktivieren; Windows: Einstellungen → Datenschutz → Mikrofon

Modell-Download schlägt fehl / extrem langsam

export HF_ENDPOINT=https://hf-mirror.com setzen und erneut ausführen

TTS gibt keinen Ton aus

Prüfen, ob das System-Ausgabegerät von einer virtuellen Soundkarte (z. B. BlackHole) gekapert wurde

Codeänderungen zeigen keine Wirkung

Der MCP-Server ist ein Dauerprozess: pkill -f "voice-dialog serve"

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

Größe

Eigenschaften

tiny

~75MB

am schnellsten, Genauigkeit durchschnittlich

base

~142MB

schnell, für den Alltag ausreichend

small (Standard)

~464MB

ausgewogen, empfohlen

medium

~1.5GB

genauer; auf M-Chips braucht die Transkription statt Sekunden zehn Sekunden

large-v3

~3GB

am genauesten und langsamsten, für kurze Dialoge nicht empfohlen

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.

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