mac-voice-mcp

🎙️ mac-voice-mcp

在 Mac 上大声与 Claude 对话。
自然轮流对话 · 设备端语音识别 · 音频不会离开你的电脑

---

Claude 通过 Mac 的扬声器说话，像真人一样聆听你的回答，并将你说的话以文本形式返回。语音识别在 Mac 上运行，因此音频不会离开你的电脑。

Claude ──speak_and_listen("Tests pass. Open the PR?")──▶  🔊 "Tests pass. Open the PR?"
                                                         🎙 you: "yes, and tag Priya"
Claude ◀──────────────── "Yes, and tag Priya." ─────────  whisper.cpp on your Mac

非常适合：

• 长时间任务：Claude 安静地工作，需要你做决定时会出声询问，这样你就可以离开屏幕。
• 快速审查：用 20 秒概述一个拉取请求，然后问一句“批准吗？”
• 在忙碌一天后让眼睛或手腕休息一下。
• 边说边思考：通过谈论问题来梳理思路，而不是打字。

功能

• 🔒 设备端处理。 whisper.cpp 在 Mac 上转录。每轮对话结束后都会删除录音。
• 💬 自然轮流对话。 轻柔提示音响起后，它会等待你开口，并在你停止说话约 1.5 秒后返回结果。无需按住按钮讲话。
• ⚡ 快速回复。 常驻运行的 whisper.cpp 服务会保持模型加载状态，因此在 Apple Silicon 上只需不到一秒就能完成转录。
• 🗣️ 自然的语音，可按需启用。 使用 macOS 中效果最佳的语音，也可选择使用 Kokoro 神经网络语音。
• ✋ 安装任何内容前都会征求同意。 设置过程会检查你已有的内容并重复利用。
• 🙋 Claude 工作时也可以和它交谈。 在任务进行中说“Claude，切换到另一个分支”，它会在下一步将其纳入考虑（Claude Code 插件）。
• 🫧 Voice Buddy（可选，Claude Code）。 提示词上方的动画伙伴会显示 Claude 正在说话还是聆听，你敲下第一个按键时会打断它。
• 🪟 一个麦克风，多个窗口。 Claude Code、Claude Desktop 和 Cursor 会轮流使用麦克风，不会互相抢话。
• 📏 实测得出，而非凭空猜测。 doctor 会在你的 Mac 上检查整条处理流程，并给出 PASS、WARN 或 FAIL 评级。

快速开始

你需要一台 Mac（推荐使用 Apple Silicon），以及 Node.js 22 或更高版本。

1. 安装。

• Claude Code（推荐）。安装插件，并一并安装 Voice Buddy：

  /plugin marketplace add jeet0007/mac-voice-mcp
  /plugin install mac-voice-mcp@mac-voice-mcp
  /plugin install voice-buddy@mac-voice-mcp
  

  Voice Buddy 是可选的：它会在提示词上方添加一个动画伙伴，还允许你通过输入文字打断（了解更多）。

• Cursor 或 VS Code：

• Claude Desktop 和其他应用： 添加 npx -y mac-voice-mcp@latest 作为 stdio MCP 服务。请参阅各应用的安装说明。

2. 设置。 让 Claude “设置语音”（或运行 /mac-voice-mcp:setup）。它会检查 SoX、whisper.cpp 和语音模型是否已安装，告诉你缺少哪些内容，并且只有在你同意后才会安装。

3. 允许使用麦克风。 Claude 首次监听时，macOS 会发出询问。点击 允许。

4. 开始对话。 运行 /mac-voice-mcp:talk fix the flaky login test，或让 Claude “需要我做决定时用语音来征求我的意见”。听到提示音后再回复。

允许语音对话轮次，无需提示

每次 Claude 想要讲话时，Claude Code 都会请求批准，这会打断对话流程。要允许语音对话轮次，请将该工具添加到 ~/.claude/settings.json 中的 permissions.allow：

{
  "permissions": {
    "allow": [
      "mcp__plugin_mac-voice-mcp_voice-mcp__speak_and_listen",
      "mcp__voice-mcp__speak_and_listen"
    ]
  }
}

第一个名称用于插件，第二个用于 claude mcp add voice-mcp …。请勿添加 voice_setup，这样安装时仍会先征求你的同意。

工作原理

此服务包含两个工具和两个提示词：

	功能
speak_and_listen	朗读一条简短消息，聆听一轮对话，并返回转录文本。
voice_setup	检查已安装的内容。征得你同意后，只安装缺少的内容。
setup prompt	引导式设置：进行检查、征求你的同意、安装，然后运行语音测试。
voice_mode prompt	免提会话，Claude 会在适当的时候通过语音征求你的意见。

Claude 会收到指示，以适合听觉接收的方式组织文字：句子简短、不使用 Markdown，并使用文件名而非路径。任何不符合要求的内容都会在朗读前改写。在 Claude Code 中，插件会让语音对话持续保持语音模式，直到你输入文字。更多信息请参阅使用方法。

故障排除

请先运行 npx -y mac-voice-mcp@latest doctor。它会测试设置、语音和转录功能，以及扬声器和麦克风，并指出失败的环节。

症状	解决方法
“麦克风返回了纯数字静音”	在系统设置 → 隐私与安全性 → 麦克风中为应用（Claude、Cursor 或终端）允许访问麦克风，然后重启应用。
我还在思考时它就打断了我	设置 VOICE_MCP_END_SILENCE_MS=2000。
语音听起来像机器人	下载 macOS Premium 语音，或安装 Kokoro。请参阅语音。
每轮对话都会请求批准	请参阅允许语音对话轮次，无需提示。

更多信息请参阅故障排除。

文档

• 安装：所有应用、MCP Registry、从克隆版本安装、升级。
• 语音：macOS Premium 语音和可选的 Kokoro 语音。
• 使用方法：语音模式、Claude 工作时与其交谈、Voice Buddy、多个会话。
• 配置：所有设置和语音模型。
• 故障排除：常见问题和已知限制。
• 隐私与安全：哪些内容保留在你的 Mac 上，以及项目如何保障安全。
• 开发：构建、测试和发布。
• 更新日志

🤖 Vibe-coded

本项目由 Claude 在对话中设计和编写。由一位人类（我）引导开发，在真实的 Mac 上进行了测试并检查了测试套件，但大部分代码由 AI 编写。在依赖本项目之前，请阅读免责声明。

免责声明

mac-voice-mcp 是一个免费的开源个人项目。它按**“原样”提供，不附带任何形式的保证**，作者不对使用本项目造成的任何损害或损失承担责任。具体条款请参阅 LICENSE。简单来说：

• 当 AI 助手调用 speak_and_listen 时，本项目会打开你的麦克风，并通过扬声器播放声音。
• 语音识别可能出错。 助手可能会根据误听的内容采取行动。在允许它执行不可撤销的操作（例如删除文件、推送代码或发送消息）之前，请检查它听到的内容。
• 本项目会在你的 Mac 上安装软件，但只有在你同意后才会安装：Homebrew 软件包；如果你选择 Kokoro 语音，还会通过 npm 安装 kokoro-js。这些是独立项目，各自采用自己的许可证（见下文）。
• 不保证提供支持。 欢迎提交问题和拉取请求，我们会尽力处理。

商标。 Apple、Mac、macOS 和 Siri 是 Apple Inc. 的商标。Claude 是 Anthropic 的商标。mac-voice-mcp 是独立项目，与 Apple 或 Anthropic 无关，也未获得它们的赞助或认可。

第三方软件

mac-voice-mcp 不会捆绑以下软件。本项目会在这些软件已安装在你的 Mac 上时使用它们，并且只会在你同意后安装。每款软件都采用各自的许可证。

软件	用途	许可证
SoX	通过麦克风录音、播放 Kokoro 音频	GPL-2.0
whisper.cpp	语音转文本	MIT
Whisper models（OpenAI）	语音转文本	MIT
macOS 语音（say）	内置语音	Apple 的 macOS 许可证
kokoro-js（可选）	Kokoro 语音	Apache-2.0
Kokoro-82M 模型（可选）	Kokoro 语音	Apache-2.0
espeak-ng（可选，包含在 kokoro-js 中）	将文本转换为 Kokoro 音频	GPL-3.0
ffmpeg（备用方案，安装脚本不会安装）	SoX 缺失时用于录音	LGPL-2.1 / GPL

许可证

MIT © Jeet