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 알림이 표시됩니다.
10개 언어에 걸쳐 54개의 음성이 있습니다. 주요 음성:
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가 Raz를 제어하는 10개 도구 | 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 shortcutMCP 서버로 등록하면 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.
