VoiceSmith MCP
用于编码助手的本地AI语音。通过模型上下文协议（MCP）为您的AI提供真实的语音（文本到语音）和耳朵（语音到文本）。完全离线——没有云API，没有数据离开你的机器。
所得
- 54种不同的声音 通过Kokoro ONNX（本地TTS，~30MB型号）
- 语音输入 通过更快的耳语（本地STT，~150MB型号）
- 话音活动检测 通过Silero VAD（本地，2MB）
- 多会话支持 --运行多个Claude Code会话，每个会话都有自己的语音（Cursor/Code为单个会话）
- 使用Claude Code、Cursor和Codex
快速开始
npx voicesmith-mcp install安装程序将：
- 检查系统依赖关系（Python 3.11+，espeak ng，mpv）
- 使用所有包设置Python虚拟环境
- 下载TTS和STT型号
- 配置IDE的MCP设置
- 让你选择一个声音
- 注入语音行为规则，使AI知道如何说话
安装后重新启动IDE会话。人工智能会在第一个响应时用语音问候你。
用法
\[！注意\] 一切都是开箱即用的。 安装后，只需启动一个会话——AI会自动说话。无需配置。安装程序设置语音行为规则，教导AI何时以及如何使用其语音。
AI会自动做什么：
| 时刻 | 发生了什么 |
|---|---|
| 你给它一个任务 | 开始工作（只在阐明方法时说话） |
| 它完成了工作 | 总结了所做的工作 |
| 它有一个问题 | 大声问，然后听你的声音回应 |
| 语音工具不可用 | 自动返回文本 |
______________________________________________________________________
中途变声
让AI随时切换声音：
*“切换到Nova”*
如果语音可用，AI会立即切换。如果它被另一个会话占用，AI会告诉你并显示可用的替代方案。
浏览所有54个声音：
*“显示可用的声音”*
或者在终端中预览它们： npx voicesmith-mcp voices
______________________________________________________________________
语音持久性
\[！提示\] 当您切换声音时，选择会自动保存。下次您开始或恢复会话时，AI会使用相同的语音，无需再次切换。
______________________________________________________________________
静音
在会议或共享空间？只要问：
*“将声音静音”*
AI继续正常工作，只是不播放音频。说 *“取消静音”* 当你准备好了。
______________________________________________________________________
菜单栏应用程序（macOS）
在macOS上，VoiceSmith包括一个用于免提控制的原生菜单栏应用程序：
- 会话活动 --使用实时火花线图查看所有活动会话
- 快速切换 --媒体回避，超时轻推
- 语音切换器 --浏览和更改54种语音，按语言嵌套
- Whisper型号 --使用内联下载进度在基本/小/中/大-v3之间切换
- 音频设备 --选择音频输出和输入设备
- 语音规则 --编辑或重置为默认值
- 更新 --检查并安装新版本
菜单栏应用程序在登录时自动启动，并独立于IDE会话运行。
______________________________________________________________________
音频设备选择
从菜单栏应用程序或配置中选择特定的音频输出（扬声器/耳机）和输入（麦克风）设备：
{
"tts": { "audio_output_device": "coreaudio/BuiltInSpeakerDevice" },
"stt": { "audio_input_device": 1 }
}更改立即生效，无需重新启动。如果配置的设备不可用，则恢复到系统默认值。
______________________________________________________________________
打断讲话
按 逃脱 而AI正在说话以立即停止音频。AI在句子中间停止并等待您的下一个输入。
替代安装
如果你没有Node.js或更喜欢shell脚本：
git clone https://github.com/shshalom/voicesmith-mcp.git
cd voicesmith-mcp
./install.sh支持相同的标志： --claude, --cursor, --codex, --all, --uninstall.
MCP工具
安装后，您的AI助手可以访问这些工具：
| 工具 | 说明 |
|---|---|
speak | 为命名代理合成和播放语音 |
listen | 打开麦克风，录制语音，返回转录文本 |
speak_then_listen | 说一个问题，然后立即听答案 |
set_voice | 更改代理名称的声音 |
get_voice_registry | 查看已分配和可用的语音 |
list_voices | 浏览所有54个科科罗的声音 |
mute / unmute | 静音或恢复语音输出 |
stop | 停止播放或取消活动录制 |
status | 服务器运行状况和会话信息 |
list_audio_devices | 列出可用的音频输入和输出设备 |
运作原理
MCP服务器与IDE一起作为本地进程运行。它通过stdio（MCP协议）进行通信。所有处理都在您的机器上进行：
- 文本转语音：Kokoro ONNX——快速神经TTS，54种声音，无需GPU
- 语音转文字：更快的耳语——OpenAI whisper通过CTranslate2在本地运行
- 语音活动检测：Silero VAD——用于干净录音的语音活动检测
- 音频：mpv用于播放；CoreAudio通过macOS上的原生应用程序包（Linux上的声音设备回退）
- 媒体回避：语音期间自动暂停Apple Music、Spotify和浏览器音频（macOS）
多会话
克劳德代码： 全面的多会话支持。多个Claude Code会话可以同时运行，每个会话都有自己的语音。会话身份通过Claude的 session_id --恢复会话会回收相同的语音，共享同一会话的多个终端共享相同的语音。孤立服务器会被自动检测和清理。
光标/代码： 仅限单次会议。Cursor每个配置运行一个MCP服务器（跨选项卡共享），Codex没有多会话挂钩。语音正常工作，只是没有多会话协调。
跨会话音频通过以下方式序列化 flock 以防止重叠播放。
配置
Config住在 ~/.local/share/voicesmith-mcp/config.json.按键设置：
{
"main_agent": "Eric",
"tts": {
"default_voice": "am_eric",
"audio_player": "mpv",
"duck_media": true
},
"stt": {
"model_size": "base",
"language": "en",
"vad_threshold": 0.3,
"nudge_on_timeout": false
}
}| 设置 | 说明 | 默认值 |
|---|---|---|
tts.duck_media | 语音时自动暂停音乐/浏览器音频（macOS） | true |
stt.nudge_on_timeout | 听完后说“我没听懂” | false |
stt.vad_threshold | 语音检测灵敏度（较低=更灵敏） | 0.3 |
重新运行 npx voicesmith-mcp install 更改您的语音或更新设置。保留现有配置，只添加新的默认值。
需求
- Python 3.11+ （推荐3.11或3.12）
- macOS （主平台）或Linux（部分支持）
- 特定的 --Kokoro的音素后端
- mpv --音频播放
- 型号约500MB磁盘空间
\[！警告\] Windows尚不受支持。 服务器使用Unix特定的功能（文件锁定、音频命令、进程检测）。计划支持Windows--请参阅 待办事项 了解详情。
支持的IDE
| IDE | 配置位置 | 规则位置 | 多会话 |
|---|---|---|---|
| 克劳德代码 | ~/.claude.json | ~/.claude/CLAUDE.md | 是（通过session_id） |
| 光标 | ~/.cursor/mcp.json | ~/.cursor/rules/voicesmith.mdc | 否（单服务器） |
| 食品法典委员会 | ~/.codex/mcp.json | ~/.codex/AGENTS.md | 否（单次会议） |
故障排除
AI听不见我（listen返回空或超时）
检查麦克风权限。 在macOS上，VoiceSmith使用本机应用程序包(VoiceSmithMCP.app)用于麦克风访问。首次录制时，macOS应显示应用程序的权限对话框。如果没有：
- 打开 系统设置>隐私和安全>麦克风
- 寻找 VoiceSmithMCP 并确保它已启用
- 如果未列出，则LaunchAgent可能未运行——请尝试重新安装：
npx voicesmith-mcp install
\[！重要\] 如果服务器检测到无声音频（约320ms为全零），它将返回一个错误，指向麦克风权限设置。这通常意味着macOS TCC拒绝麦克风访问。
检查您的音频输入设备。 如果选择了外部麦克风但未连接，服务器会打开它但会静音：
- 打开 系统设置>声音>输入 并验证是否选择了正确的麦克风
- 或者问AI： *“服务器状态如何？”* --检查一下
stt.loaded和vad.loaded两者都true
另一个应用程序正在使用麦克风。 Zoom、Teams或FaceTime等应用程序可以拥有独家麦克风访问权限。请关闭它们，然后重试。
声音对VAD来说太安静了。 语音活动检测器可能无法检测到软语音。您可以在中降低灵敏度阈值 ~/.local/share/voicesmith-mcp/config.json:
{
"stt": {
"vad_threshold": 0.2
}
}值越低=越敏感。默认值为 0.3。更改后重新启动会话。
AI不会说话
- 检查一下 特定的 和 mpv 已安装：
which espeak-ng mpv - 检查AI的状态：询问 *“你的声音状态如何？”*
- 如果静音，请说 *“取消静音”*
AI用错误的声音说话
当另一个会话使用您的首选语音名称时，可能会发生这种情况。问AI： *“切换到Eric”* --它要么会切换，要么会告诉你有什么可用的。
卸载
npx voicesmith-mcp uninstall
# or if installed via git clone:
./install.sh --uninstall彻底删除所有文件、模型、MCP配置条目、语音规则、LaunchAgent和挂钩。
许可证
Apache 2.0