🚀 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许可证。