de en es ja ko ru zh

Raz

Name: Raz
Author: Mateob6

by Mateob6

Overview Schema Related Servers Score Discussions

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와 대화하기 (누르고 말하기)

키보드의 오른쪽 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 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

그런 다음 단축키를 지정하세요:

시스템 설정 → 키보드 → 키보드 단축키 → 서비스 → 일반
"Activar Raz" 를 찾으세요
"단축키 추가"를 클릭하고 원하는 키 조합을 누르세요 (예: ⌃⌘R)

이제 해당 키 조합으로 어디서든 Raz를 켜고 끌 수 있으며, macOS 알림이 표시됩니다.

음성

10개 언어에 걸쳐 54개의 음성이 있습니다. 주요 음성:

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가 Raz를 제어하는 10개 도구	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

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

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

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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