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,不上传任何音频。

License

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,重启会话即可用。

也可以手动,就两条命令:

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