使用说明

语音MCP服务器

可以在Claude Code中进行语音对话的MCP服务器。

单目标跟踪：MLX Whisper（Apple Silicon优化）
文本转语音：Kokoro（多语言支持：日语、英语、中文等）
语音活动检测：Silero VAD+RMS双过滤器

当前代码 韩语输入→日语输出硬编码为。更改为其他语言的步骤语言更改指南请参阅部分。

要求

macOS（苹果硅M1/M2/M3）
Python 3.11或更高版本
Claude 代码命令行界面
麦克风（MacBook内置麦克风或外置麦克风）

安装

1.存储库克隆

git clone https://github.com/jeonghyeon-net/voice-mcp-demo.git
cd voice-mcp-demo

2.安装Python3.11（如果没有）

brew install python@3.11

3.创建和激活虚拟环境

python3.11 -m venv venv
source venv/bin/activate

4.安装依赖性

pip install -r requirements.txt

5.下载型号

python setup_models.py

⚠️ 必需：使用Claude Code前请务必运行。提前下载Whisper、Kokoro TTS和Silero VAD型号。首次运行时下载约2-3 GB。

6.确认安装

# VAD 테스트 (마이크 테스트)
python test_vad.py

换句话说，应该显示阴性概率。

MCP设置

~/.mcp.json 创建或修改文件：

{
  "mcpServers": {
    "voice": {
      "command": "/경로/voice-mcp-demo/venv/bin/python",
      "args": ["/경로/voice-mcp-demo/voice_mcp.py"]
    }
  }
}

/경로/请将更改为实际路径。

使用方法

在Claude Code中：

> listen

输入后，将启动语音识别模式。

工具

工具	说明
`listen()`	用麦克风听语音（韩语）
`speak(text)`	用日语TTS回复
`listen_fixed(duration)`	固定时间录音

流

listen 输入→哔哔声后说话
Claude用日语回答（speak)
继续或结束对话

验证MCP服务器注册

Claude Code运行后 /mcp 输入：

> /mcp
✓ voice (connected)

voice如果已连接，则准备就绪。

对话示例

> listen

⏺ voice - listen (MCP)
  ⎿ { "result": "[사용자]: 안녕하세요\n\n⚠️ ..." }

⏺ voice - speak (MCP)(text: "こんにちは！何かお手伝いできますか？")
  ⎿ { "result": "→ listen() 호출하세요" }

⏺ voice - listen (MCP)
  ⎿ { "result": "[사용자]: 오늘 날씨 어때?\n\n⚠️ ..." }

...

结束语音对话

说“结束”、“拜拜”、“谢谢”等，Claude就会结束对话。
或Ctrl+C强制退出
超时（5分钟内不说话自动关闭）

提示

首次运行时 加载模型需要一段时间（TTS介绍“初化中”）
说话的时候 比夫酒后等0.5秒左右再说
话结束的时候 安静1.5秒后开始识别
Claude回答后 自动重听模式（可能需要手动输入listen）

设定值

voice_mcp.py可在中调整：

设置	默认值	说明
`VAD_THRESHOLD` 0.85语音检测阈值
`RMS_THRESHOLD` 0.02卷阈值
`SILENCE_DURATION` 1.5秒沉默后结束时间
`timeout_seconds` 300秒最大等待时间

语言更改指南

默认值为 韩语输入→日语输出是。要更改为其他语言，请：

更改为英语TTS

voice_mcp.py 修改：

# 1. TTS 언어 코드 변경 (get_tts 함수)
_tts = KPipeline(lang_code='a', repo_id='hexgrad/Kokoro-82M')
# 'a' = 미국 영어, 'b' = 영국 영어, 'j' = 일본어
# 'k' = 한국어, 'z' = 중국어, 'f' = 프랑스어 등

# 2. 음성 변경 (speak 함수의 기본값)
def speak(text: str, voice: str = "af_heart", speed: float = 1.0) -> str:
# 영어 음성: af_heart, af_bella, am_adam, am_michael 등

Kokoro支持的语言

代码语言 |------|------| | a |美国英语| | b |英国英语| | j |日语| | z |中文| | f |法语| | e |西班牙语| | i |意大利语| | p |葡萄牙语| | h |印地语|

参考：Kokoro 82M不支持韩语TTS。如果需要韩语语音输出，请使用其他TTS引擎（Edge TTS、Google TTS等）。

英语语音列表

语音说明 |------|------| | af_heart |美国女性（默认推荐）| | af_bella |美国女性| | af_sarah |美国女性| | am_adam |美国男性| | am_michael |美国男性| | bf_emma |英国女性| | bm_george |英国男性|

speak（）更改提示

让Claude用英语回答 speak 修改函数的docstring：

@mcp.tool()
def speak(text: str, voice: str = "af_heart", speed: float = 1.0) -> str:
    """
    Speak in English.

    ⚠️ Text must be in English only!

    Args:
        text: English text
        voice: Voice
        speed: Speed

    Returns:
        Playback complete
    """

更改输入语言

listen() 更改函数的默认language参数：

def listen(timeout_seconds: int = 300, language: str = "en") -> str:
# "ko" = 한국어, "en" = 영어, "ja" = 일본어

完整的英语设置示例

# get_tts()
_tts = KPipeline(lang_code='a', repo_id='hexgrad/Kokoro-82M')

# listen()
def listen(timeout_seconds: int = 300, language: str = "en") -> str:

# speak()
def speak(text: str, voice: str = "af_heart", speed: float = 1.0) -> str:
    """Speak in English. Text must be in English only!"""

动作原理

整个流程

[사용자] --말함--> [마이크] --오디오--> [Silero VAD] --음성구간--> [Whisper] --텍스트--> [Claude]
                                                                                        |
[사용자] <--듣기-- [스피커] <--오디오-- [Kokoro TTS] <--텍스트------------------------------+

1.语音检测（VAD）

# Silero VAD가 음성 확률 계산 (0.0 ~ 1.0)
speech_prob = vad_model(chunk_tensor, SAMPLE_RATE)

# RMS(볼륨)도 함께 체크해서 배경 소음 필터링
rms = np.sqrt(np.mean(chunk ** 2))

# 둘 다 임계값 넘어야 음성으로 인식
is_voice = speech_prob > 0.85 and rms > 0.02

2.语音识别（STT）

# MLX Whisper - Apple Silicon GPU 가속
result = mlx_whisper.transcribe(
    audio_data,
    path_or_hf_repo="mlx-community/whisper-medium-mlx",
    language="ko"  # 한국어
)

3.语音合成（TTS）

# Kokoro TTS - 일본어 음성 생성
tts = KPipeline(lang_code='j', repo_id='hexgrad/Kokoro-82M')
for _, _, audio in tts(text, voice='jf_alpha', speed=1.0):
    sd.play(audio, 24000)

MCP通信

Claude Code <--stdio--> voice_mcp.py (FastMCP 서버)
                            |
                            ├── listen()   # 도구 1
                            ├── speak()    # 도구 2
                            └── listen_fixed()  # 도구 3

模型上下文协议（MCP）是允许Claude Code调用外部工具的协议。 ~/.mcp.json在注册服务器后，Claude可以使用这些工具。

项目结构

voice-mcp-demo/
├── voice_mcp.py      # MCP 서버 메인
├── setup_models.py   # 모델 사전 다운로드
├── echo.py           # 독립 실행 버전 (Ollama 연동)
├── run.sh            # echo.py 실행 스크립트
├── test_vad.py       # VAD 테스트 도구
├── requirements.txt  # 의존성
└── README.md

测试

# VAD 테스트
./venv/bin/python test_vad.py

# 독립 실행 (echo.py)
./run.sh

故障排除

无法识别语音

检查麦克风权限
降低RMS_THRESHOLD（0.01）

对背景噪音有反应

VAD_THRESHOLD提高（0.9）
提高RMS_THRESHOLD（0.03）

MCP连接失败

检查python路径
python -m py_compile voice_mcp.py语法检查

许可证

麻省理工学院