Skip to main content
Glama
deenesjakoruzh
Mateob6

Raz

by Mateob6
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Raz — Claude Code 的语音界面

用你的声音与 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 进行语音对话。代码块和表格会被静默跳过——只朗读散文文本。

环境要求

要求

原因

Apple Silicon Mac（M1/M2/M3/M4）

kokoro-mlx 和 mlx-whisper 仅在 Apple Silicon 上运行

Python 3.12

固定版本——kokoro-mlx 需要它

Claude Code

本工具集成的 CLI

uv

Python 包管理器（处理所有依赖）

jq

用于 CLI 的 JSON 处理（brew install jq）

安装设置

整个安装过程大约需要 5 分钟。每一步都可以直接复制粘贴。

第 1 步：克隆并安装

git clone https://github.com/Mateob6/claude-voice-interaction.git
cd claude-voice-interaction
uv sync

这会下载代码并在隔离的虚拟环境中安装所有 Python 依赖（kokoro-mlx、mlx-whisper、FastAPI、pynput 等）。

第 2 步：安装 CLI

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

第 3 步：注册 MCP 服务器

这使 Claude Code 可以通过 10 个内置工具（说话、更换语音、开始/停止监听等）控制 Raz：

claude mcp add raz -- uv run --directory "$(pwd)" python -m raz.mcp_server

第 4 步：设置自动朗读

此钩子使 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 获取该路径。

第 5 步：首次运行

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 stop

使用 Raz

开始语音会话

raz start    # start voice + mic
raz stop     # stop everything
raz status   # check what's running

与 Claude 对话（按住说话）

  1. 按住键盘上的右 Option (⌥) 键

  2. 说出你的消息

  3. 松开按键

  4. 你的话会被转录并粘贴到 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 voices

调整语速

raz 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

然后分配快捷键：

  1. 系统设置 → 键盘 → 键盘快捷键 → 服务 → 通用

  2. 找到 "Activar Raz"

  3. 点击"添加快捷键"并按下你偏好的组合键（例如 ⌃⌘R）

现在，该组合键可以在任何地方切换 Raz 的开关，并带有 macOS 通知。

语音

54 种语音，涵盖 10 种语言。亮点：

ID

语言

性别

特点

em_alex

西班牙语

♂

默认。 自然、清晰

ef_dora

西班牙语

♀

温暖、富有表现力

af_heart

英语

♀

整体质量最佳

am_adam

英语

♂

低沉、清晰

bm_fable

英式英语

♂

讲故事的声音

ff_siwis

法语

♀

清晰、自然

if_sara

意大利语

♀

温暖、悦耳

jf_alpha

日语

♀

标准

zf_xiaoxiao

普通话

♀

充满活力

pf_dora

葡萄牙语

♀

自然

完整列表：raz voices

配置

自动朗读模式

模式

作用

smart

朗读散文文本，静默跳过代码和表格 （默认）

auto

朗读所有内容

off

不自动朗读——仅显式调用 speak() MCP

raz mode smart    # recommended
raz mode auto     # hear everything
raz mode off      # silent, use speak() when needed

语言检测

Raz 会自动检测文本是西班牙语还是英语，并相应地切换语音。如果你设置了 em_alex（西班牙语男声），而 Claude 用英语回复，Raz 会自动为该回复切换到 am_adam（英语男声），然后再切回来。

STT 语言

按住说话守护进程默认为西班牙语。使用其他语言启动它：

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 内存。

故障排除

"右 Option 键没有反应"

你的终端应用需要辅助功能权限。前往系统设置 → 隐私与安全性 → 辅助功能，然后添加你的终端（iTerm2、Terminal.app 等）。

"raz start 卡在 'Loading Whisper model'"

首次运行会下载 Whisper 模型（约 800 MB）。请检查你的网络连接。模型在首次下载后会被缓存。

"端口 8787 已被占用"

另一个 Raz 实例正在运行。结束它：

raz stop
# If that doesn't work:
pkill -f "raz.tts_server"

"守护进程无法停止"

pkill -f "run_daemon"

"没有声音输出"

检查你的 Mac 音频输出设置是否正确（系统设置 → 声音）。Raz 通过默认输出设备播放。

CLI 参考

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 工具

注册为 MCP 服务器后，Claude Code 将获得这 10 个工具：

工具

作用

speak(text, voice?, speed?)

朗读文本

set_voice(voice)

更换语音

list_voices()

列出所有语音

set_mode(mode)

更改自动朗读模式

set_speed(speed)

调整语速

toggle(enabled?)

启用/禁用 TTS

status()

检查 Raz 状态

stt_start(language?)

开始按住说话

stt_stop()

停止按住说话

stt_status()

检查麦克风状态

许可证

MIT

This server cannot be installed

-
license - not tested
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

  • local-mcp

    Let ChatGPT, Claude & Cursor use your Mac: email, calendar, iMessage, Teams, files. Local, free.

  • WHOOP — MissingMCP

    WHOOP recovery, strain, sleep and workouts in Claude via official WHOOP OAuth. Free, open source.

  • RogerRat

    Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Mateob6/claude-voice-interaction'

If you have feedback or need assistance with the MCP directory API, please join our Discord server