金大哥 - voice-mcp MCP 详情

article

README

🚀 voice-mcp - Claude Code的语音模式

voice-mcp是一个模型上下文协议（MCP）服务器，它能让你与Claude及其他大语言模型（LLMs）进行语音交互。你只需要一个OpenAI API密钥，以及麦克风和扬声器即可使用。

🚀 快速开始

Claude Code的设置

export OPENAI_API_KEY=your-openai-key
claude mcp add voice-mcp uvx voice-mcp
# 或者，运行容器镜像
# docker pull ghcr.io/mbailey/voice-mcp:latest
# claude mcp add voice-mcp podman run -e OPENAI_API_KEY ghcr.io/mbailey/voice-mcp:latest
claude

你可以尝试说："让我们进行语音对话"

Claude桌面端设置

将以下内容添加到Claude桌面端的配置文件中：

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

使用uvx（推荐）

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

使用Docker/Podman

{
  "mcpServers": {
    "voice-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--device", "/dev/snd",
        "-e", "PULSE_RUNTIME_PATH=/run/user/1000/pulse",
        "-v", "/run/user/1000/pulse:/run/user/1000/pulse",
        "ghcr.io/mbailey/voice-mcp:latest"
      ],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

使用pip安装

{
  "mcpServers": {
    "voice-mcp": {
      "command": "voice-mcp",
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

✨ 主要特性

🎙️ 语音对话：与Claude进行语音交流，提问并听取回答。
🔄 多种传输方式：支持本地麦克风或基于LiveKit房间的通信。
🗣️ 兼容OpenAI：可与任何语音识别（STT）/文本转语音（TTS）服务（本地或云端）配合使用。
⚡ 实时交互：低延迟语音交互，自动选择传输方式。
🔧 MCP集成：与Claude桌面端和其他MCP客户端无缝集成。

📦 安装指南

简单要求

你只需要准备好以下两样东西即可开始使用：

🔑 OpenAI API密钥（或兼容服务）：用于语音识别和文本转语音。
🎤 配备麦克风和扬声器的计算机 或者 ☁️ LiveKit服务器（LiveKit云服务或自托管）

💻 使用示例

基础用法

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

"让我们进行语音对话"
"用语音询问我的一天"
"给我讲个笑话"（Claude会说话并等待你的回应）
"说再见"（Claude会说话但不等待回应）

新的 converse 函数让语音交互更加自然，默认情况下它会自动等待你的回应。

📚 详细文档

工具

| 工具 | 描述 | 关键参数 | |------|-------------|----------------| | converse | 说话并可选择监听回应 | wait_for_response（默认：true），listen_duration（默认：10s） | | listen_for_speech | 仅监听并转录语音 | duration（默认：5s） | | check_room_status | 显示LiveKit房间状态 | 无 | | check_audio_devices | 列出音频设备 | 无 |

配置

必需配置

export OPENAI_API_KEY="your-key"

可选配置

# 自定义服务（兼容OpenAI）
export STT_BASE_URL="http://localhost:2022/v1"  # 本地Whisper
export TTS_BASE_URL="http://localhost:8880/v1"  # 本地TTS
export TTS_VOICE="af_sky"                       # 天空语音（Kokoro）
export TTS_MODEL="tts-1"
export STT_MODEL="whisper-1"

# LiveKit（用于基于房间的通信）
export LIVEKIT_URL="wss://your-app.livekit.cloud"
export LIVEKIT_API_KEY="your-api-key"
export LIVEKIT_API_SECRET="your-api-secret"

# 调试
export VOICE_MCP_DEBUG="true"

故障排除

没有麦克风：检查系统权限。
未找到UV：运行 curl -LsSf https://astral.sh/uv/install.sh | sh。
API错误：验证 OPENAI_API_KEY。
调试模式：设置 VOICE_MCP_DEBUG=true（将音频保存到 ~/voice-mcp_recordings/）。

📄 许可证

本项目采用MIT许可证。

voice-mcp