voice-dialog

Un servidor MCP que añade capacidad de conversación por voz a los agentes de IA, y que también puede usarse como herramienta de línea de comandos. Cuando el agente termina su trabajo, puede decírtelo hablando, y también puede preguntarte y escuchar tu respuesta. El reconocimiento se ejecuta en whisper local, y la síntesis usa el TTS del sistema; no se necesita conexión a internet en todo el proceso ni se envían audios.

Qué puede hacer

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

Related MCP server: Pipecat MCP Server

Inicio rápido

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 es una guía totalmente automática de 7 pasos: instala uv → instala dependencias (uv incluso te instala Python) → descarga el modelo whisper (464 MB; con red de China usa automáticamente hf-mirror) → prueba real de permisos de micrófono → prueba real de salida de TTS → imprime el comando de registro de MCP. Si un paso falla, te da el comando para arreglarlo; una vez arreglado, vuelve a ejecutarlo.

Prueba una frase:

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

Conecta tu agente

Cualquier cliente MCP (Claude Code, Codex, Cursor, LoopX…):

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

Registro en una línea con Claude Code:

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

Herramientas que no admiten MCP: llama directamente a la CLI, uv run voice-dialog speak/listen/ask "...".

Claude Code Skill (opcional, enseña al agente cuándo hablar/escuchar): copia skills/voice-dialog/ a ~/.claude/skills/.

Plataformas compatibles

Detección automática de idioma (whisper admite ~100 idiomas); VD_LANG=zh permite fijarlo; el tamaño del modelo se ajusta con VD_MODEL=small.

Preguntas frecuentes

Privacidad

La voz se reconoce localmente (faster-whisper), el texto se reproduce con el TTS del sistema, no se llama a ninguna API en la nube y no se sube ningún audio.

Licencia

MIT

Notas sobre el modelo

¿Qué se descarga por defecto? whisper small (cuantización int8, ~464 MB), el punto de equilibrio entre precisión y velocidad para reconocer chino e inglés. Se descarga automáticamente la primera vez que se ejecuta listen/init, y luego queda en caché local (macOS/Linux: ~/.cache/huggingface/hub/, Windows: %USERPROFILE%\.cache\huggingface\hub\); nunca se vuelve a descargar.

¿Cómo se elige la fuente de descarga? El código no fija la lógica de descarga: al construir WhisperModel("small", ...), la librería faster-whisper descarga automáticamente desde HuggingFace. Por defecto usa la fuente oficial huggingface.co; si no se puede conectar con la fuente oficial, el código cambia automáticamente al espejo nacional hf-mirror.com y reintenta (se hace configurando la variable de entorno HF_ENDPOINT). Los usuarios en China también pueden fijarlo manualmente de antemano:

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

¿Quieres cambiar a un modelo más grande? Lo controla la variable de entorno VD_MODEL; vuelve a ejecutar para que surta efecto:

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

Instalación desde zip (sin git clone)

Descarga el zip (o que un amigo te lo envíe directamente) → descomprímelo donde quieras, por ejemplo ~/tools/ → abre la terminal y entra en el directorio, y deja el resto a la IA:

En Claude Code (o cualquier herramienta de IA de programación que pueda ejecutar comandos), envíale el siguiente bloque tal cual:

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

Instalará todo y lo registrará en Claude Code; reinicia la sesión y ya podrás usarlo.

También puedes hacerlo manualmente, solo dos comandos:

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

Si no estás familiarizado con la terminal en Mac: tras descomprimir, haz clic derecho en la carpeta → Servicios → Nueva terminal en la carpeta, y ya estarás en el directorio.