livechat-mcp
livechat-mcp
一个模型上下文协议 (MCP) 服务器,让您可以与 AI 编程助手进行连续的语音对话。您说话,语音会在本地通过 Whisper 转录,每段话语都会像您输入一样发送给助手。无需切换标签页,无需复制/粘贴,无需批量录音。
适用于任何 MCP 主机。对以下工具提供一流支持:
Claude Code
Codex CLI
Gemini CLI
要求
macOS、Linux 或 Windows(通过 PowerShell 原生运行,或在 WSL2 / Git Bash 下运行)。
Python 3.10+
已安装 MCP 主机(Claude Code、Codex、Gemini 等)
可用的麦克风
~500 MB 磁盘空间用于 Whisper 模型缓存 + 依赖项
uv用于项目管理(推荐)
Related MCP server: Voice MCP
快速安装(推荐)
从仓库克隆后:
# macOS / Linux / Git Bash on Windows
./install.sh# Native Windows PowerShell
.\install.ps1引导程序会自动检测操作系统,在需要时安装 portaudio(brew / apt / dnf / pacman / zypper — Windows wheel 已捆绑),如果缺少 uv 则安装它,运行 uv sync,将向导放入 ~/.local/bin,并启动交互式设置向导。
Windows:原生锁定使用
msvcrt,接管信号基于文件,因此没有fcntl依赖。交互式向导是一个 bash 脚本 —install.ps1通过 Git Bash 调用它,如果缺少 Git Bash,它会建议通过winget安装。
手动设置
如果您更喜欢一步步安装,以下是 install.sh 所做的工作:
1. 安装 portaudio
sounddevice 需要 portaudio。
macOS:
brew install portaudioDebian/Ubuntu:
sudo apt-get install libportaudio2 portaudio19-devFedora/RHEL:
sudo dnf install portaudio portaudio-develArch:
sudo pacman -S portaudio
2. 如果没有 uv,请安装它
curl -LsSf https://astral.sh/uv/install.sh | sh3. 克隆并安装依赖项
cd livechat-mcp
uv sync这将创建 .venv/ 并安装 mcp、faster-whisper、sounddevice、silero-vad、torch 等。
4. 运行设置向导
install -m 0755 bin/livechat-mcp ~/.local/bin/livechat-mcp
livechat-mcp setup向导将:
询问要为哪些助手安装(Claude Code / Codex / Gemini,任意组合)。
将
/livechat和/endlivechat斜杠命令复制到支持自定义斜杠命令的主机。对于 Codex,它会同时安装旧版提示文件和livechat技能,因为当前的 Codex CLI 版本不会将自定义提示公开为/livechat。在每个主机的配置文件中注册 MCP 服务器。
指导您完成可调环境变量(静音阈值、Whisper 模型等)的设置 — 按回车键保留默认值。
确保 ~/.local/bin 在您的 PATH 中(如果您使用了官方的 uv 安装程序,它已经在其中了)。
如果您更喜欢手动连接,每个主机的具体步骤如下。
5. 授予麦克风权限
macOS: 服务器第一次尝试捕获音频时,macOS 会提示您的 终端应用(Terminal、iTerm、Ghostty、Warp 等)获取麦克风访问权限。如果您错过了提示,请手动启用:
系统设置 → 隐私与安全性 → 麦克风 → 为您的终端启用
如果您跳过此步骤,音频捕获将静默返回静音,且永远不会进行转录。
Windows: 设置 → 隐私与安全性 → 麦克风 → 允许桌面应用访问麦克风(并确保您的终端已获得许可)。
Linux: 通常没有提示 — 只需确保您的用户拥有正确的 ALSA / PulseAudio / Pipewire 访问权限(通常是
audio组)。
6. 预下载 Whisper 模型(可选)
首次运行时会下载 base.en(约 150 MB)。您可以预先加载它:
uv run python -c "from faster_whisper import WhisperModel; WhisperModel('base.en', device='cpu', compute_type='int8')"手动安装(如果您使用了 livechat-mcp setup,请跳过此部分)
Claude Code
复制斜杠命令:
mkdir -p ~/.claude/commands
cp commands/livechat.md ~/.claude/commands/
cp commands/endlivechat.md ~/.claude/commands/注册 MCP 服务器:
claude mcp add livechat -- uv --directory "$(pwd)" run livechat-mcp或者直接编辑 ~/.claude.json:
{
"mcpServers": {
"livechat": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/livechat-mcp", "run", "livechat-mcp"]
}
}
}Codex CLI
安装 Codex 技能和旧版提示文件:
mkdir -p ~/.codex/skills/livechat
cp skills/livechat/SKILL.md ~/.codex/skills/livechat/
mkdir -p ~/.codex/prompts
cp commands/livechat.md ~/.codex/prompts/
cp commands/endlivechat.md ~/.codex/prompts/在 ~/.codex/config.toml 中注册 MCP 服务器:
[mcp_servers.livechat]
command = "uv"
args = ["--directory", "/absolute/path/to/livechat-mcp", "run", "livechat-mcp"]Gemini CLI
Gemini 使用 TOML 进行自定义命令。向导会为您生成这些文件;若要手动操作,请参阅 commands/gemini/livechat.toml.template(通过运行 livechat-mcp setup 一次创建)。
在 ~/.gemini/settings.json 中注册 MCP 服务器:
{
"mcpServers": {
"livechat": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/livechat-mcp", "run", "livechat-mcp"]
}
}
}使用方法
在任何终端中打开助手的 CLI:
claude # or: codex or: gemini然后在助手提示符中:
/livechat # Claude Code, Gemini CLI
use livechat # Codex CLI需要重启 Codex。 Codex 仅在启动时加载技能和 MCP 服务器。如果您在 Codex 打开时运行了向导,请在执行
use livechat之前退出并重新启动。
Codex 0.128.0 不支持用户定义的 /livechat 斜杠命令;/ 目前保留给 Codex 的内置命令。设置程序会安装一个可发现的 livechat 技能,因此您可以输入 use livechat 或打开 /skills 并选择 livechat。
助手将调用 get_voice_input 并开始监听。正常说话即可。 当您暂停约 1.5 秒时,您的语音会被定稿、转录并作为提示发送。助手会做出响应,然后立即监听下一段话语。
当助手正在生成响应时,麦克风仍然处于开启状态 — 在此期间您说的任何内容都会排队,并在下一次 get_voice_input 调用时一次性发送。
结束会话
有三种方法:
/endlivechat— 最干净的方法,从助手提示符运行。(如果正在响应中,您需要先中断当前轮次。)唤醒短语 — 说
terminate voice session now。转录会触发关闭。该短语特意设置得比较生硬,以避免与实际评论内容冲突。可通过LIVECHAT_END_PHRASE配置。Ctrl+C — 终止 MCP 服务器。助手将在下一次调用时看到工具错误并停止循环。
配置
所有可调参数位于 livechat_mcp/config.py 中,可以通过环境变量覆盖:
变量 | 默认值 | 说明 |
|
| 仅限英语: |
|
| 语言代码( |
|
|
|
|
|
|
|
| 语音后的静音时间,用于结束一段话语 |
|
| Silero VAD 语音概率阈值 |
|
| 最小话语长度(过滤咳嗽声) |
|
| 强制截断过长的话语 |
|
|
|
|
| 用于结束会话的口语短语 |
| 未设置 | 设置为 |
设置这些参数的简单方法是 livechat-mcp set KEY VALUE — 它会编辑它找到的每个主机配置(Claude / Codex / Gemini)中的 env 块。
livechat-mcp show # print current env block(s)
livechat-mcp set LIVECHAT_SILENCE_SEC 1.5
livechat-mcp unset LIVECHAT_DEBUG更改后请重启您的助手 CLI — MCP 环境变量在服务器启动时读取。
若要手动操作,请编辑每个主机配置中 livechat MCP 条目的 env 字段。以 Claude Code 为例:
{
"mcpServers": {
"livechat": {
"command": "uv",
"args": ["--directory", "/abs/path", "run", "livechat-mcp"],
"env": {
"LIVECHAT_WHISPER_MODEL": "small.en",
"LIVECHAT_DEBUG": "1"
}
}
}
}故障排除
说话时没有反应。
检查(按顺序):终端应用的麦克风权限、麦克风输入电平(系统设置 → 声音)、设置 LIVECHAT_DEBUG=1 并观察 stderr 中的 VAD 事件、将 LIVECHAT_VAD_THRESHOLD 降低到 0.3。
转录不准确。
升级模型:LIVECHAT_WHISPER_MODEL=small.en 或 medium.en。medium.en 在 CPU 上明显较慢(但仍接近实时),但对技术词汇的处理效果好得多。
话语结束得太快 / 太慢。
调整 LIVECHAT_SILENCE_SEC(或运行 livechat-mcp set LIVECHAT_SILENCE_SEC 1.5)。1.0–4.5 是有效范围 — 较低的值感觉更灵敏,但有中断思考停顿的风险。
找不到 uv。
要么安装 uv(推荐),要么将 MCP 配置中的 command 更改为在激活的 venv 中直接调用 python -m livechat_mcp.server。
服务器启动了,但助手从不调用该工具。
确保已调用 /livechat。如果没有斜杠命令,助手就没有进入循环的指令。
服务器日志作为乱码进入助手的 UI / 破坏了协议。
这不应该发生 — 所有服务器日志都发送到 stderr。如果您看到了,请提交 bug。确保您没有添加任何没有 file=sys.stderr 的 print(...) 语句。
启动时出现 portaudio 错误。
安装它:brew install portaudio。如果已安装但仍然失败,请尝试 brew reinstall portaudio 并重新安装 sounddevice:uv sync --reinstall。
工作原理(简述)
[mic] → [Silero VAD] → [Whisper] → [queue] ← [get_voice_input tool] ← [Assistant]
↑________background thread, always running________↑音频管道与 MCP 工具解耦,因此只要服务器运行,麦克风就始终处于开启状态。在助手生成响应时所说的话语会被排队,并在下一次工具调用时发送。
Available Tools
4 toolsend_voice_sessionA
Cleanly end the current voice session. After calling this, any further get_voice_input calls will return 'END_SESSION'. Use this when the user invokes /endlivechat or otherwise asks to stop voice mode.
Inputs: no named parameters.
get_voice_inputA
Returns the next voice utterance from the user as text. Used in a loop during voice review sessions. If multiple utterances are queued, they are joined with ' / '. Returns the literal string 'END_SESSION' when the user has ended the session (Ctrl+C, /endlivechat, or wake phrase) — stop calling this tool when you see that. Returns 'NO_INPUT' if the long-poll timed out with no speech; in that case, call this tool again. Returns 'ALREADY_RUNNING:' if another livechat MCP process (e.g. another Claude Code window) currently holds the session lock — ask the user to confirm a takeover, then call take_over_voice_session if they agree.
Inputs: no named parameters.
reset_voice_sessionA
Clear stale shutdown state from a previous /endlivechat in this same MCP server process so a new voice session can start cleanly. Call this once at the very beginning of a /livechat session, after the announcement and before the first get_voice_input. Safe to call mid-session: if a session is already running healthily this is a no-op and no in-flight utterances are dropped.
Inputs: no named parameters.
take_over_voice_sessionA
Forcibly take the cross-process session lock from another livechat MCP instance. Signals the holder to release, waits briefly, and starts a new session here. Only call this after the user explicitly confirms taking over from the other window. Returns 'OK' on success or an error string on failure.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: retrieving input, ending the session, taking over a lock, and resetting state. No overlap or ambiguity between them.
All tool names follow a consistent verb_noun snake_case pattern (e.g., get_voice_input, end_voice_session). The pattern is uniform and predictable.
Four tools is well-scoped for a voice session lifecycle. Each tool serves a necessary function with no redundancy, fitting the server's narrow purpose.
The tool surface covers the full voice session lifecycle: starting clean, retrieving input, ending, and handling cross-process takeover. No obvious dead ends or missing operations for the intended use case.
Maintenance
Related MCP Connectors
Speech, transcription, voice agents, Trace, Recap, dubbing and narration with browser OAuth.
Command your AI agents by voice: PTT rooms, channels, direct messages, agent email, memory (mRAG).
Turn calls and notes into process flow diagrams in Claude, ChatGPT, VS Code, Cursor, and Teams.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceEnables coding agents to speak aloud using text-to-speech functionality. Works with agents running inside devcontainers and provides configurable voice settings for creating chatty AI companions.6-
- FlicenseNot gradedqualityDmaintenanceEnables voice interaction with Claude Code through local speech-to-text (Whisper) and text-to-speech (Supertonic), allowing verbal input/output without external API calls.2-
- FlicenseNot gradedqualityDmaintenanceEnables natural voice interaction with Claude Code through speech-to-text, supporting wake word activation and multiple backends like Whisper and Google. It allows users to execute commands and control their coding environment hands-free via their microphone.2-
- AlicenseNot gradedqualityDmaintenanceEnables bidirectional voice interaction for Claude Code using local speech-to-text and text-to-speech models optimized for Apple Silicon. It provides tools to listen to user speech via microphone and speak responses aloud through system speakers.16Apache 2.0