shield_lock
金大哥
联系我们
← 返回 MCP 目录
public公开dns本地运行

voicemode

Voice Mode是一个为AI助手提供自然语音对话功能的工具，支持与Claude、ChatGPT等LLM通过MCP协议进行人机语音交互。

article

README

🚀 语音模式

语音模式为AI助手带来自然的语音对话体验。它通过模型上下文协议（MCP），为Claude、ChatGPT等大语言模型（LLMs）赋予类似人类的语音交互能力。

🚀 快速开始

📖 使用其他工具？ 查看我们针对Cursor、VS Code、Gemini CLI等工具的 集成指南！

npm install -g @anthropic-ai/claude-code
curl -LsSf https://astral.sh/uv/install.sh | sh
claude mcp add --scope user voice-mode uvx voice-mode
export OPENAI_API_KEY=your-openai-key
claude converse

✨ 主要特性

  • 🎙️ 语音对话：与Claude进行语音交流，提问并听取回复。
  • 🔄 多种传输方式：支持使用本地麦克风或基于LiveKit房间的通信方式。
  • 🗣️ 兼容OpenAI：可与任何语音识别（STT）/文本转语音（TTS）服务（本地或云端）配合使用。
  • ⚡ 实时交互：低延迟语音交互，自动选择传输方式。
  • 🔧 MCP集成：与Claude Desktop等MCP客户端无缝集成。
  • 🎯 静音检测：当你停止说话时自动停止录音（无需再等待！）

📦 安装指南

前提条件

  • Python >= 3.10
  • Astral UV：包管理器（使用 curl -LsSf https://astral.sh/uv/install.sh | sh 进行安装）
  • OpenAI API密钥（或兼容服务）

系统依赖

Ubuntu/Debian 
sudo apt update
sudo apt install -y python3-dev libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev ffmpeg pulseaudio pulseaudio-utils

WSL2用户注意：WSL2需要额外的音频包（pulseaudio、libasound2-plugins）才能访问麦克风。如果遇到问题，请查看我们的 WSL2麦克风访问指南。

Fedora/RHEL 
sudo dnf install python3-devel alsa-lib-devel portaudio-devel ffmpeg
macOS 
# 如果尚未安装Homebrew，请先安装
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装依赖
brew install portaudio ffmpeg
Windows (WSL)

在WSL中遵循上述Ubuntu/Debian的安装说明。

NixOS

语音模式包含一个flake.nix文件，其中包含所有必需的依赖项。你可以选择以下方式之一：

  1. 使用开发环境（临时）：
nix develop github:mbailey/voicemode
  1. 系统级安装（见下文安装部分）

快速安装

# 使用Claude Code（推荐）
claude mcp add --scope user voice-mode uvx voice-mode

# 在NixOS上使用Claude Code
claude mcp add voice-mode nix run github:mbailey/voicemode

# 使用UV
uvx voice-mode

# 使用pip
pip install voice-mode

# 在NixOS上使用Nix
nix run github:mbailey/voicemode

AI编码助手的配置

📖 寻找详细的设置说明？ 查看我们全面的 集成指南，获取每个工具的分步说明！

以下是快速配置片段。完整的安装和设置说明，请参考上述集成指南。

Claude Code (CLI) 
claude mcp add voice-mode -- uvx voice-mode

或者使用环境变量：

claude mcp add voice-mode --env OPENAI_API_KEY=your-openai-key -- uvx voice-mode
Claude Desktop

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "voice-mode": {
      "command": "uvx",
      "args": ["voice-mode"],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}
Cline

添加到你的Cline MCP设置中：

Windows：

{
  "mcpServers": {
    "voice-mode": {
      "command": "cmd",
      "args": ["/c", "uvx", "voice-mode"],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

macOS/Linux：

{
  "mcpServers": {
    "voice-mode": {
      "command": "uvx",
      "args": ["voice-mode"],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}
Continue

添加到你的 .continue/config.json 文件中：

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uvx",
          "args": ["voice-mode"],
          "env": {
            "OPENAI_API_KEY": "your-openai-key"
          }
        }
      }
    ]
  }
}
Cursor

添加到 ~/.cursor/mcp.json 文件中：

{
  "mcpServers": {
    "voice-mode": {
      "command": "uvx",
      "args": ["voice-mode"],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}
VS Code

添加到你的VS Code MCP配置中：

{
  "mcpServers": {
    "voice-mode": {
      "command": "uvx",
      "args": ["voice-mode"],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}
Windsurf 
{
  "mcpServers": {
    "voice-mode": {
      "command": "uvx",
      "args": ["voice-mode"],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}
Zed

添加到你的Zed settings.json 文件中：

{
  "context_servers": {
    "voice-mode": {
      "command": {
        "path": "uvx",
        "args": ["voice-mode"],
        "env": {
          "OPENAI_API_KEY": "your-openai-key"
        }
      }
    }
  }
}
Roo Code
  1. 打开VS Code设置 (Ctrl/Cmd + ,)
  2. 在设置搜索栏中搜索 "roo"
  3. 找到 "Roo-veterinaryinc.roo-cline → settings → Mcp_settings.json"
  4. 点击 "在settings.json中编辑"
  5. 添加语音模式配置：
{
  "mcpServers": {
    "voice-mode": {
      "command": "uvx",
      "args": ["voice-mode"],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

其他安装选项

使用Docker 
docker run -it --rm \
  -e OPENAI_API_KEY=your-openai-key \
  --device /dev/snd \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -e DISPLAY=$DISPLAY \
  ghcr.io/mbailey/voicemode:latest
使用pipx 
pipx install voice-mode
从源代码安装 
git clone https://github.com/mbailey/voicemode.git
cd voicemode
pip install -e .
NixOS安装选项

1. 使用nix profile安装（用户级）：

nix profile install github:mbailey/voicemode

2. 添加到NixOS配置（系统级）：

# 在 /etc/nixos/configuration.nix 中
environment.systemPackages = [
  (builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];

3. 添加到home-manager：

# 在home-manager配置中
home.packages = [
  (builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];

4. 不安装直接运行：

nix run github:mbailey/voicemode

💻 使用示例

配置完成后，可尝试向Claude发送以下提示：

👨‍💻 编程与开发

  • "让我们一起调试这个错误" - 口头解释问题，粘贴代码，并讨论解决方案。
  • "帮我讲解这段代码" - 让Claude解释复杂代码，同时你可以提问。
  • "让我们一起构思架构" - 通过自然对话设计系统。
  • "帮我为这个函数编写测试" - 描述需求并进行口头迭代。

💡 通用生产力

  • "让我们进行每日站会" - 练习演讲或整理思路。
  • "就[主题]对我进行面试" - 通过问答为面试做准备。
  • "做我的橡皮鸭调试伙伴" - 口头解释问题以找到解决方案。

🎯 语音控制功能

  • "朗读这条错误信息"（Claude朗读后等待你的回复）
  • "给我一个快速总结"（Claude直接朗读，无需等待）
  • 使用 converse("message", wait_for_response=False) 进行单向播报。

converse 函数使语音交互自然流畅，默认情况下会自动等待你的回复，营造真实的对话流程。

📚 详细文档

支持的工具

语音模式可与你喜爱的AI编码助手配合使用：

工具说明

| 工具 | 描述 | 关键参数 | |------|------|----------| | converse | 进行语音对话 - 说话并可选择听取回复 | message，wait_for_response（默认：true），listen_duration（默认：30s），transport（自动/本地/LiveKit） | | listen_for_speech | 监听语音并转换为文本 | duration（默认：5s） | | check_room_status | 检查LiveKit房间状态和参与者 | 无 | | check_audio_devices | 列出可用的音频输入/输出设备 | 无 | | start_kokoro | 启动Kokoro TTS服务 | models_dir（可选，默认为 ~/Models/kokoro） | | stop_kokoro | 停止Kokoro TTS服务 | 无 | | kokoro_status | 检查Kokoro TTS服务的状态 | 无 | | install_whisper_cpp | 安装whisper.cpp以实现本地语音识别 | install_dir，model（默认：base.en），use_gpu（自动检测） | | install_kokoro_fastapi | 安装kokoro-fastapi以实现本地文本转语音 | install_dir，port（默认：8880），auto_start（默认：true） |

注意：converse 工具是语音交互的主要接口，它将说话和倾听自然地结合在一起。

新增：install_whisper_cpp 和 install_kokoro_fastapi 工具可帮助你在本地设置免费、私密的开源语音服务。详细用法请参阅 安装工具文档。

配置

快速设置

唯一需要配置的是你的OpenAI API密钥：

export OPENAI_API_KEY="your-key"

可选设置

# 自定义STT/TTS服务（兼容OpenAI）
export STT_BASE_URL="http://127.0.0.1:2022/v1"  # 本地Whisper
export TTS_BASE_URL="http://127.0.0.1:8880/v1"  # 本地TTS
export TTS_VOICE="alloy"                        # 语音选择

# 或者使用语音偏好文件（请参阅配置文档）
# 项目级：/your-project/voices.txt 或 /your-project/.voicemode/voices.txt
# 用户级：~/voices.txt 或 ~/.voicemode/voices.txt

# LiveKit（用于基于房间的通信）
# 有关设置指南，请参阅 docs/livekit/
export LIVEKIT_URL="wss://your-app.livekit.cloud"
export LIVEKIT_API_KEY="your-api-key"
export LIVEKIT_API_SECRET="your-api-secret"

# 调试模式
export VOICEMODE_DEBUG="true"

# 保存所有音频（TTS输出和STT输入）
export VOICEMODE_SAVE_AUDIO="true"

# 音频格式配置（默认：pcm）
export VOICEMODE_AUDIO_FORMAT="pcm"         # 选项：pcm, mp3, wav, flac, aac, opus
export VOICEMODE_TTS_AUDIO_FORMAT="pcm"     # 仅覆盖TTS的格式（默认：pcm）
export VOICEMODE_STT_AUDIO_FORMAT="mp3"     # 覆盖STT上传的格式

# 特定格式的质量设置
export VOICEMODE_OPUS_BITRATE="32000"       # Opus比特率（默认：32kbps）
export VOICEMODE_MP3_BITRATE="64k"          # MP3比特率（默认：64k）

音频格式配置

语音模式默认使用 PCM 音频格式进行TTS流式传输，以实现最佳实时性能：

  • PCM（TTS默认）：零延迟，最佳流式传输性能，未压缩。
  • MP3：广泛兼容，适合上传的良好压缩格式。
  • WAV：未压缩，适合本地处理。
  • FLAC：无损压缩，适合存档。
  • AAC：良好的压缩格式，适用于苹果生态系统。
  • Opus：文件小，但不建议用于流式传输（存在质量问题）。

音频格式会根据提供商的能力自动验证，如果需要，会回退到支持的格式。

本地STT/TTS服务

为了保护隐私或实现离线使用，语音模式支持本地语音服务：

  • Whisper.cpp - 具有兼容OpenAI API的本地语音识别服务。
  • Kokoro - 具有多种语音选项的本地文本转语音服务。

这些服务提供与OpenAI相同的API接口，允许在云端和本地处理之间无缝切换。

OpenAI API兼容性优势

通过严格遵循OpenAI的API标准，语音模式实现了强大的部署灵活性：

  • 🔀 透明路由：用户可以在语音模式之外实现自己的API代理或网关，根据自定义逻辑（成本、延迟、可用性等）将请求路由到不同的提供商。
  • 🎯 模型选择：部署路由层，为每个请求选择最佳模型，而无需修改语音模式的配置。
  • 💰 成本优化：构建智能路由器，在昂贵的云API和免费的本地模型之间进行平衡。
  • 🔧 无锁定：只需更改 BASE_URL 即可切换提供商，无需更改代码。

示例：只需将 OPENAI_BASE_URL 设置为指向你的自定义路由器：

export OPENAI_BASE_URL="https://router.example.com/v1"
export OPENAI_API_KEY="your-key"
# 语音模式现在将所有OpenAI API调用发送到你的路由器

OpenAI SDK会自动处理这些操作，无需对语音模式进行配置！

🔧 技术细节

架构

┌─────────────────────┐     ┌──────────────────┐     ┌─────────────────────┐
│   Claude/LLM        │     │  LiveKit Server  │     │  Voice Frontend     │
│   (MCP Client)      │◄────►│  (Optional)     │◄───►│  (Optional)         │
└─────────────────────┘     └──────────────────┘     └─────────────────────┘
         │                            │
         │                            │
         ▼                            ▼
┌─────────────────────┐     ┌──────────────────┐
│  Voice MCP Server   │     │   Audio Services │
│  • converse         │     │  • OpenAI APIs   │
│  • listen_for_speech│◄───►│  • Local Whisper │
│  • check_room_status│     │  • Local TTS     │
│  • check_audio_devices    └──────────────────┘
└─────────────────────┘

故障排除

常见问题

  • 无法访问麦克风：检查终端/应用程序的系统权限。
  • 未找到UV：使用 curl -LsSf https://astral.sh/uv/install.sh | sh 进行安装。
  • OpenAI API错误：验证你的 OPENAI_API_KEY 是否设置正确。
  • 无音频输出：检查系统音频设置和可用设备。

调试模式

启用详细日志记录和音频文件保存：

export VOICEMODE_DEBUG=true

调试音频文件将保存到：~/voicemode_recordings/

音频诊断

运行诊断脚本检查你的音频设置：

python scripts/diagnose-wsl-audio.py

该脚本将检查所需的包和音频服务，并提供具体建议。

音频保存

保存所有音频文件（TTS输出和STT输入）：

export VOICEMODE_SAVE_AUDIO=true

音频文件将保存到：~/voicemode_audio/，文件名包含时间戳。

文档

📚 在voice-mode.readthedocs.io阅读完整文档

入门指南

开发

服务指南

故障排除

相关链接

社区

其他参考

📄 许可证

本项目采用MIT许可证，由 Failmode 发起。

项目统计

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端