用你的声音与 Claude Code 对话。Claude 会回话。一切都在你的 Mac 上本地运行——没有云 API、没有订阅、没有数据离开你的机器。
Raz（源自亚拉姆语 רָז，意为"被揭示的奥秘"）使用 kokoro-mlx 进行语音合成、mlx-whisper 进行语音识别，为 Claude Code 赋予了声音和耳朵，两者均针对 Apple Silicon 进行了优化。
You speak (hold Right Option key) ──► Whisper transcribes ──► text goes to Claude
Claude responds ──► auto-speak reads the response aloud through your speakers就是这样。当 Raz 开启时，你可以与 Claude 进行语音对话。代码块和表格会被静默跳过——只朗读散文文本。
Related MCP server: Voice MCP
要求 | 原因 |
Apple Silicon Mac（M1/M2/M3/M4） | kokoro-mlx 和 mlx-whisper 仅在 Apple Silicon 上运行 |
Python 3.12 | 固定版本——kokoro-mlx 需要它 |
本工具集成的 CLI | |
Python 包管理器（处理所有依赖） | |
jq | 用于 CLI 的 JSON 处理（ |
整个安装过程大约需要 5 分钟。每一步都可以直接复制粘贴。
git clone https://github.com/Mateob6/claude-voice-interaction.git
cd claude-voice-interaction
uv sync这会下载代码并在隔离的虚拟环境中安装所有 Python 依赖（kokoro-mlx、mlx-whisper、FastAPI、pynput 等）。
mkdir -p ~/.local/bin
ln -sf "$(pwd)/scripts/raz" ~/.local/bin/raz
chmod +x scripts/raz scripts/start_server.sh scripts/stop_server.sh确保 ~/.local/bin 在你的 PATH 中。如果没有：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc验证是否安装成功：
raz help这使 Claude Code 可以通过 10 个内置工具（说话、更换语音、开始/停止监听等）控制 Raz：
claude mcp add raz -- uv run --directory "$(pwd)" python -m raz.mcp_server此钩子使 Claude 的回复自动朗读出来。将其添加到你的 Claude Code 设置中：
cat ~/.claude/settings.json如果文件存在，添加 hooks 部分。如果不存在，则创建它：
{
"hooks": {
"Stop": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "/FULL/PATH/TO/claude-voice-interaction/hooks/stop_hook.sh",
"timeout": 30
}
]
}
]
}
}重要提示： 将 /FULL/PATH/TO/claude-voice-interaction 替换为你克隆仓库的实际路径。你可以在项目目录中运行 pwd 获取该路径。
raz start这会启动两个组件：
TTS 服务器（文本转语音）——加载 kokoro-mlx 模型（首次约 10 秒）
STT 守护进程（语音转文本）——监听右 Option 键
你应该会看到：
=== Starting Raz ===
Starting Raz TTS server (background) on port 8787...
Raz ready!
Starting STT daemon (lang=es)...
Loading Whisper model. ready!
PID: 12345测试一下：
raz say "Hello, I can speak now"如果你听到了声音，说明一切正常。使用以下命令停止 Raz：
raz stopraz start # start voice + mic
raz stop # stop everything
raz status # check what's running按住键盘上的右 Option (⌥) 键
说出你的消息
松开按键
你的话会被转录并粘贴到 Claude Code 中
录音开始时你会听到一声 Tink，停止时会听到一声 Pop。
首次使用： macOS 会请求你的终端应用的辅助功能权限。请授予该权限——pynput 需要它来全局检测热键。
首次按键： Whisper 模型在首次使用时加载（约 3 秒）。之后，转录几乎是即时的。模型在空闲 5 分钟后会自动卸载以释放内存。
raz voice af_heart # switch to English female (best quality)
raz voice em_alex # switch to Spanish male (default)
raz voice bm_fable # switch to British storyteller
raz voices # see all 54 voicesraz speed 1.5 # faster
raz speed 0.8 # slower
raz speed 1.0 # normal录制音频并将转录内容复制到剪贴板（无需守护进程）：
raz listen # Spanish (default)
raz listen en # English
# Press Ctrl+C when done speaking使用全局键盘快捷键从任何应用中切换 Raz 的开关：
raz shortcut install然后分配快捷键：
系统设置 → 键盘 → 键盘快捷键 → 服务 → 通用
找到 "Activar Raz"
点击"添加快捷键"并按下你偏好的组合键（例如 ⌃⌘R）
现在，该组合键可以在任何地方切换 Raz 的开关，并带有 macOS 通知。
54 种语音，涵盖 10 种语言。亮点：
ID | 语言 | 性别 | 特点 |
| 西班牙语 | ♂ | 默认。 自然、清晰 |
| 西班牙语 | ♀ | 温暖、富有表现力 |
| 英语 | ♀ | 整体质量最佳 |
| 英语 | ♂ | 低沉、清晰 |
| 英式英语 | ♂ | 讲故事的声音 |
| 法语 | ♀ | 清晰、自然 |
| 意大利语 | ♀ | 温暖、悦耳 |
| 日语 | ♀ | 标准 |
| 普通话 | ♀ | 充满活力 |
| 葡萄牙语 | ♀ | 自然 |
完整列表：raz voices
模式 | 作用 |
| 朗读散文文本，静默跳过代码和表格 （默认） |
| 朗读所有内容 |
| 不自动朗读——仅显式调用 |
raz mode smart # recommended
raz mode auto # hear everything
raz mode off # silent, use speak() when neededRaz 会自动检测文本是西班牙语还是英语，并相应地切换语音。如果你设置了 em_alex（西班牙语男声），而 Claude 用英语回复，Raz 会自动为该回复切换到 am_adam（英语男声），然后再切回来。
按住说话守护进程默认为西班牙语。使用其他语言启动它：
raz stt start en # English
raz stt start es # Spanish (default)Claude Code
├── MCP tools (10) ──► localhost:8787 (TTS: kokoro-mlx)
│ ──► raz.stt.daemon (STT: control)
├── Stop hook ──► localhost:8787/auto-speak
├── STT daemon (pynput + mlx-whisper) ──► clipboard ──► paste
└── CLI (raz) ──► unified lifecycle组件 | 作用 | 内存 |
TTS 服务器 | 通过扬声器朗读文本（FastAPI + kokoro-mlx） | 约 730 MB |
STT 守护进程 | 监听右 Option 键，使用 Whisper 转录 | 空闲约 2 MB，加载 Whisper 后约 4 GB |
MCP 服务器 | 为 Claude Code 提供 10 个控制 Raz 的工具 | 在 Claude Code 内运行 |
停止钩子 | 捕获 Claude 的回复并将其发送到 TTS | bash 脚本，不占内存 |
STT 守护进程在首次按键时延迟加载 Whisper，并在空闲 5 分钟后自动卸载以释放约 4 GB 内存。
你的终端应用需要辅助功能权限。前往系统设置 → 隐私与安全性 → 辅助功能，然后添加你的终端（iTerm2、Terminal.app 等）。
首次运行会下载 Whisper 模型（约 800 MB）。请检查你的网络连接。模型在首次下载后会被缓存。
另一个 Raz 实例正在运行。结束它：
raz stop
# If that doesn't work:
pkill -f "raz.tts_server"pkill -f "run_daemon"检查你的 Mac 音频输出设置是否正确（系统设置 → 声音）。Raz 通过默认输出设备播放。
raz start # Start Raz (voice + mic)
raz stop # Stop Raz
raz on / raz off # Enable/disable Raz
raz status # Show Raz status
raz say "text" # Speak text
raz listen [lang] # Record → transcribe → clipboard
raz voice NAME # Change voice
raz voices # List all 54 voices
raz mode MODE # smart | auto | off
raz speed N # 0.5–2.0
raz stt start|stop # Mic only
raz tts start|stop # Voice only
raz shortcut install|remove # Keyboard shortcut注册为 MCP 服务器后，Claude Code 将获得这 10 个工具：
工具 | 作用 |
| 朗读文本 |
| 更换语音 |
| 列出所有语音 |
| 更改自动朗读模式 |
| 调整语速 |
| 启用/禁用 TTS |
| 检查 Raz 状态 |
| 开始按住说话 |
| 停止按住说话 |
| 检查麦克风状态 |
This server cannot be deployed
Let cloud agents talk to you: progress updates spoken on your Mac, and replies you send back.
No-data MCP handoff for local Claude Code to Codex harness moves. $49 lifetime.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Mac & Windows: let ChatGPT, Claude & Cursor use your email, calendar, iMessage, Teams, files.
