
VoiceMode
MCP让 Claude Code 等 agent 支持语音对话:说话后自动检测静音并识别,回复直接朗读出来。可用本地 Whisper 与 Kokoro 离线运行,也可接 OpenAI 语音接口;需要麦克风和扬声器。
VoiceMode
Natural voice conversations with Claude Code (and other MCP capable agents)
New, 9 Nov 2026: Session Kit, from the people who brought you VoiceMode. A voice, a phone line and mail for your Claude Code sessions. Works on macOS; preliminary testing on Linux.
VoiceMode enables natural voice conversations with Claude Code. Voice isn't about replacing typing - it's about being available when typing isn't.
Perfect for:
- Walking to your next meeting
- Cooking while debugging
- Giving your eyes a break after hours of screen time
- Holding a coffee (or a dog)
- Any moment when your hands or eyes are busy
See It In Action
Quick Start
Requirements: Computer with microphone and speakers
Option 1: Claude Code Plugin (Recommended)
The fastest way for Claude Code users to get started:
# Add the VoiceMode marketplace
claude plugin marketplace add mbailey/voicemode
# Install VoiceMode plugin
claude plugin install voicemode@voicemode
## Install dependencies (CLI, Local Voice Services)
/voicemode:install
# Start talking!
/voicemode:converse
Option 2: Python installer package
Installs dependencies and the VoiceMode Python package.
# Install UV package manager (if needed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Run the installer (sets up dependencies and local voice services)
uvx voice-mode-install
# Add to Claude Code
claude mcp add --scope user voicemode -- uvx --refresh --from voice-mode voicemode-mcp-launcher
# Optional: Add OpenAI API key as fallback for local services
export OPENAI_API_KEY=your-openai-key
# Start a conversation
claude converse
For manual setup, see the Getting Started Guide.
Features
- Natural conversations - speak naturally, hear responses immediately
- Works offline - optional local voice services (Whisper STT, Kokoro TTS)
- Low latency - fast enough to feel like a real conversation
- Smart silence detection - stops recording when you stop speaking
- Privacy options - run entirely locally or use cloud services
Compatibility
Platforms: Linux, macOS, Windows (native or WSL), NixOS Python: 3.10-3.14
Configuration
VoiceMode works out of the box. For customization:
# Set OpenAI API key (if using cloud services)
export OPENAI_API_KEY="your-key"
# Or configure via file
voicemode config edit
See the Configuration Guide for all options.
Permissions Setup (Optional)
To use VoiceMode without permission prompts, add to ~/.claude/settings.json:
{
"permissions": {
"allow": [
"mcp__voicemode__converse",
"mcp__voicemode__service"
]
}
}
See the Permissions Guide for more options.
Local Voice Services
For privacy or offline use, install local speech services:
- Whisper.cpp - Local speech-to-text
- Kokoro - Local text-to-speech with multiple voices
These provide the same API as OpenAI, so VoiceMode switches seamlessly between them.
Installation Details
System Dependencies by Platform
Ubuntu/Debian
sudo apt update
sudo apt install -y ffmpeg gcc libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev pulseaudio pulseaudio-utils python3-dev
WSL2 users: The pulseaudio packages above are required for microphone access.
Fedora/RHEL
sudo dnf install alsa-lib-devel ffmpeg gcc portaudio portaudio-devel python3-devel
macOS
brew install ffmpeg node portaudio
NixOS
# Use development shell
nix develop github:mbailey/voicemode
# Or install system-wide
nix profile install github:mbailey/voicemode
Alternative Installation Methods
From source
git clone https://github.com/mbailey/voicemode.git
cd voicemode
uv tool install -e .
NixOS system-wide
# In /etc/nixos/configuration.nix
environment.systemPackages = [
(builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];
Troubleshooting
| Problem | Solution |
|---|---|
| No microphone access | Check terminal/app permissions. WSL2 needs pulseaudio packages. |
| UV not found | Run curl -LsSf https://astral.sh/uv/install.sh | sh |
| OpenAI API error | Verify OPENAI_API_KEY is set correctly |
| No audio output | Check system audio settings and available devices |
Save Audio for Debugging
export VOICEMODE_SAVE_AUDIO=true
# Files saved to ~/.voicemode/audio/YYYY/MM/
Documentation
- Getting Started - Full setup guide
- Configuration - All environment variables
- Whisper Setup - Local speech-to-text
- Kokoro Setup - Local text-to-speech
- Development Setup - Contributing guide
Full documentation: voicemode.dev
Links
- Website: voicemode.dev
- GitHub: github.com/mbailey/voicemode
- PyPI: pypi.org/project/voice-mode
- YouTube: @getvoicemode
- Twitter/X: @getvoicemode
- Newsletter:
License
MIT - A Failmode Project
mcp-name: dev.voicemode/voicemode
相關資源

WhisperX
CLI基于 faster-whisper 的快速语音转写,提供词级时间戳与说话人分离,适合会议纪要与字幕制作;说话人分离需 Hugging Face Token,GPU 加速需 CUDA。
m-bain/whisperX25.5k
whisper-ctranslate2
CLI本地语音转写工具,与 OpenAI Whisper 命令行兼容但更快更省内存,可输出 SRT / VTT 字幕与文本,支持麦克风实时转写,适合整理课堂录音、访谈与会议。需要 Python,首次运行自动下载模型;区分说话人需另装 pyannote.audio 并提供 Hugging Face Token。
Softcatala/whisper-ctranslate21.4k
Browser Use MCP
MCPBrowser Use 官方内置的本地 MCP 服务:让 agent 导航、点击、输入、提取网页内容,或把多步任务交给内置浏览器 agent 自主完成。需自备 OpenAI 或 Anthropic API Key。
browser-use/browser-use121k
Whisper
CLIOpenAI 官方开源的通用语音识别模型,自带 whisper 命令,可多语种转写、把外语语音翻译成英文并输出字幕文件;需要 FFmpeg,有 GPU 时更快。
openai/whisper113k
Fetch MCP Server
MCPMCP 官方参考服务器:抓取网页并转成 Markdown 供模型阅读,支持从指定位置分段读取长页面。零配置,但能访问内网地址,使用时注意安全。
modelcontextprotocol/servers92.1k
Time MCP Server
MCP为 agent 提供当前时间查询与 IANA 时区换算,自动识别系统时区,无需 API Key。MCP 官方参考服务器,Python 实现。
modelcontextprotocol/servers92.1k
