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 用于项目管理（推荐）

快速安装（推荐）

从仓库克隆后：

# 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 portaudio

• Debian/Ubuntu: sudo apt-get install libportaudio2 portaudio19-dev

• Fedora/RHEL: sudo dnf install portaudio portaudio-devel

• Arch: sudo pacman -S portaudio

2. 如果没有 uv，请安装它

curl -LsSf https://astral.sh/uv/install.sh | sh

3. 克隆并安装依赖项

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

向导将：

1. 询问要为哪些助手安装（Claude Code / Codex / Gemini，任意组合）。

2. 将 /livechat 和 /endlivechat 斜杠命令复制到支持自定义斜杠命令的主机。对于 Codex，它会同时安装旧版提示文件和 livechat 技能，因为当前的 Codex CLI 版本不会将自定义提示公开为 /livechat。

3. 在每个主机的配置文件中注册 MCP 服务器。

4. 指导您完成可调环境变量（静音阈值、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 调用时一次性发送。

结束会话

有三种方法：

1. /endlivechat — 最干净的方法，从助手提示符运行。（如果正在响应中，您需要先中断当前轮次。）

2. 唤醒短语 — 说 terminate voice session now。转录会触发关闭。该短语特意设置得比较生硬，以避免与实际评论内容冲突。可通过 LIVECHAT_END_PHRASE 配置。

3. Ctrl+C — 终止 MCP 服务器。助手将在下一次调用时看到工具错误并停止循环。

配置

所有可调参数位于 livechat_mcp/config.py 中，可以通过环境变量覆盖：

设置这些参数的简单方法是 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 工具解耦，因此只要服务器运行，麦克风就始终处于开启状态。在助手生成响应时所说的话语会被排队，并在下一次工具调用时发送。