Pronunciation & Voice Coach

mcp-server-pronunciation

准确性与安全提示

本项目是一款本地语言学习练习工具。它可能包含错误、 运行时错误、不准确的转录、不准确的发音反馈或特定平台的录音问题。发音反馈是用于辅导的 信号，不是标准化考试、临床、就业或其他高风险 评估。依赖输出前请仔细检查。请参阅 DISCLAIMER.md。

一个 MCP（Model Context Protocol）服务，可让你通过语音与 MCP 助手对话，并在同一轮对话中获得英语发音、语法和流利度反馈。可用于带有轻度辅导的随意语音聊天，也可以在想练习特定句子时切换到训练模式。

专为 Codex CLI、Claude Desktop、Claude Code、Cursor、VS Code 及其他 MCP 客户端打造。所有操作均在本地运行——音频由麦克风采集，通过设备上的 faster-whisper 转录，绝不会离开你的设备。

mcp-name: io.github.JuhongPark/pronunciation

原因

如今的语音 MCP 服务把语音当作打字的替代方式。英语辅导 MCP 服务则只有文本。此项目将两者结合起来：你自由发言，助手回复，而对你刚才所说内容的反馈（发音、语法、流利度）会在同一次工具调用中呈现，让助手可以将其自然地融入回复；如果你只是在聊天，也可以不予理会。

功能

• 与 MCP 助手进行语音对话。开口说话，静音时自动停止，然后让助手读取你的转录并作出回应。
• 音素级训练反馈（提供参考句时）：Needleman-Wunsch 单词对齐、每个单词的预期与实际产出 IPA、学习者档案提示、最小对立体练习，以及韵律检查（单词重音、句末升调、分句内停顿）。
• 可扩展的学习者档案支持：当前规则集包含韩语母语发音模式提示和韩语提示。欢迎贡献其他母语档案。
• 缓解 Whisper 偏差（通过可选的 [phoneme] 附加组件）：wav2vec2 CTC 强制对齐会验证用户是否确实说出了每个参考单词，因此 Whisper 将生僻专有名词和特定领域术语改写为更常见的替代词时，不再会将其判定为发音错误。
• 对话中的英语反馈：发音、语法（常见不规则动词错误）和流利度（语速和长时间停顿）。
• 训练模式（practice、quick_practice、retry），用于专注练习句子。
• 仅限本地运行：Whisper 模型在你的设备上运行，音频不会离开设备。
• 跨平台：macOS、Linux、Windows 和 WSL2（录音会自动通过 Windows 路由）。
• 快速启动：延迟导入与后台模型预加载使 MCP 握手耗时不到一秒。

要求

• Python 3.11+
• 可正常使用的麦克风
• 默认 Whisper 模型（base.en）需要约 150 MB 磁盘空间
• 安装可选的 [phoneme] 附加组件还需要约 360 MB（用于强制对齐的 wav2vec2 权重）
• MCP 规范：通过官方 Python SDK 使用 2025-06-18，需要 mcp>=1.2

安装

稳定版

安装最新稳定版：

uvx mcp-server-pronunciation

pip 用户请运行：

pip install mcp-server-pronunciation

如需明确固定此版本：

uvx [email protected]

在实际会话中使用该服务前，请先运行 doctor：

mcp-server-pronunciation doctor

常规安装命令

# Recommended: uvx (no global install, cached between runs)
uvx mcp-server-pronunciation

# Or install as a uv tool
uv tool install mcp-server-pronunciation

# Or pip
pip install mcp-server-pronunciation

# Optional: forced-alignment upgrade for Whisper-bias mitigation + tighter
# phoneme-level feedback. Adds ~200 MB of torch CPU wheels.
pip install 'mcp-server-pronunciation[phoneme]'

Linux：先安装 PortAudio

macOS 和 Windows 上的 sounddevice 会在 wheel 中附带 PortAudio，但在 Linux 上，你需要安装系统库：

# Debian / Ubuntu
sudo apt-get install libportaudio2

# Fedora / RHEL
sudo dnf install portaudio

# Arch
sudo pacman -S portaudio

# PipeWire-only systems may also need
sudo apt-get install pipewire-alsa

首次检查

将服务接入 MCP 客户端前，请先运行预检：

uvx mcp-server-pronunciation doctor

可选——预先下载 Whisper 模型（约 150 MB），使首次调用即时完成：

uvx mcp-server-pronunciation pull-model base.en

添加到 MCP 客户端

Codex CLI

codex mcp add pronunciation -- uvx mcp-server-pronunciation

Claude Code

claude mcp add pronunciation -- uvx mcp-server-pronunciation

Claude Desktop

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "pronunciation": {
      "command": "uvx",
      "args": ["mcp-server-pronunciation"]
    }
  }
}

在 macOS 上，如果 Claude Desktop 找不到 uvx（spawn uvx ENOENT），请使用绝对路径。在终端中运行 which uvx 查找路径。

Cursor

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "pronunciation": {
      "command": "uvx",
      "args": ["mcp-server-pronunciation"]
    }
  }
}

VS Code（支持 MCP）

添加到 .vscode/mcp.json 或用户设置中：

{
  "servers": {
    "pronunciation": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-pronunciation"]
    }
  }
}

使用示例

1. 通过语音聊天获取反馈

你：“我们来语音聊天吧。我会问你一些关于周末的事。请使用 converse 工具。”

助手（调用 converse）：录下你的语音，将其转录，并注意到你说的是 “buyed” 而不是 “bought”

助手：“哦，不错——你买了哪种苹果？顺便说一下，‘buy’ 的过去式是 ‘bought’——只是个小问题，不过我注意到了。”

2. 针对特定句子进行练习

你：“给我一句带有 ‘th’ 音的练习句。”

助手（调用 suggest_sentence，参数为 focus=th）：“试试这句：The three brothers thought thoroughly about their future.”

你：“录下我读这句话的声音。”

助手（使用该参考句调用 practice）：返回一张对齐表（匹配／替换／插入／删除）；安装 [phoneme] 附加组件后，还会返回每个单词的声学置信度、包含预期 IPA 与实际发音对比的音素级问题、适用时的学习者档案提示、最小对立体练习，以及韵律说明（单词重音、句尾升调、分句内停顿）。

3. 根据反馈重试

你：“让我再试一次。”

助手（调用 retry）：重新录制同一句目标句，并进行比较

工具

工具	用途
converse	主要工具。录音 + 转录 + 快速反馈 + 助手指导，适用于自然的语音聊天与辅导。
practice	练习模式：录制用户朗读指定参考句，并返回详细评估。
quick_practice	按音素重点和难度随机选取一句话并进行练习。
retry	重新录制上次的句子，并将新尝试与之前的尝试进行比较。
open_voice_panel	客户端支持嵌入式 UI 时，打开 MCP Apps 语音面板。
analyze_uploaded_audio	分析从语音面板上传的 WAV 音频，并将其存储为最新的语音录音。
start_voice_capture	在后台开始录音，并立即返回会话 ID。
voice_capture_status	检查后台录音是正在录制、正在分析、已完成、已取消还是失败。
wait_for_voice_capture	等待后台录音完成，并返回转录文本和反馈。
latest_voice_capture	返回最近一次后台录音结果。
cancel_voice_capture	在分析开始前将后台录音标记为已取消。
suggest_sentence	返回练习句，但不录音。
record	录制音频并保存为 WAV 文件（原始音频，不进行分析）。
assess	评估上次录音（或指定的 WAV 文件），不重新录音。提供参考句时，会运行完整的练习流程（对齐、音素差异、学习者档案提示、韵律）。
check_mic	列出可用的音频输入设备。

评估语音的工具还会返回结构化 MCP 输出，其中包含 transcript、 clarity_pct、speaking_rate_wpm、top_issue、next_action、 retry_comparison、完整的机器可读 assessment，以及渲染后的 report_markdown。MCP 客户端可以使用结构化结果来提供重试选项、 突出显示首要问题，或构建更丰富的练习 UI，而无需解析 Markdown。

可视化语音录制工作流

对于没有内置语音界面的 MCP 客户端，请使用后台录制工具，让用户了解进度：

start_voice_capture(duration=8, mode="conversation")
voice_capture_status(session_id)
wait_for_voice_capture(session_id, timeout=30)
latest_voice_capture()

状态响应包含 recording、analyzing、done、error 或 cancelled，以及已用时间、转录文本、清晰度、语速、反馈 Markdown 和完整的结构化评估（如果有）。在 WSL2 上，请将 duration 设得较短，因为 PowerShell 录制可能会一直等待到请求的时长结束后才开始分析。

MCP Apps 语音面板

支持 MCP Apps 的客户端可以调用 open_voice_panel 来呈现 ui://pronunciation/voice-panel 资源。该面板会请求浏览器麦克风访问权限，在浏览器本地录音，通过 analyze_uploaded_audio 上传 WAV 音频片段，并显示返回的转录文本和反馈。 上传的音频必须是可读取的 16 位 PCM RIFF/WAVE 文件，采用单声道或立体声音频，采样率为 8-48 kHz，大小不超过 20 MB，时长不超过 120 秒。

上传的音频片段会与仅通过 MCP 录制的音频存储在同一语音会话注册表中，因此助手可以在面板 完成后调用 latest_voice_capture，同时回应开发备注和发音 反馈。不支持 MCP Apps 的客户端应使用上文的可视化 语音录制工作流。

提示词快捷方式

可展示服务端提示词的 MCP 客户端可以直接启动常见工作流：

提示词	用途
start_voice_chat	开始本地语音对话，并提供简要反馈。
daily_practice	运行简短的推荐句子练习循环。
practice_focus	针对选定的重点和难度开始专项练习。
troubleshoot_mic	检查麦克风设备和录音设置。

配置

Whisper 模型

设置 MCP_PRONUNCIATION_MODEL 以选择不同的模型大小：

# Default — fast, English-only (~150 MB)
export MCP_PRONUNCIATION_MODEL=base.en

# Smaller / faster (~75 MB)
export MCP_PRONUNCIATION_MODEL=tiny.en

# More accurate (~470 MB)
export MCP_PRONUNCIATION_MODEL=small.en

# Multilingual options (larger)
export MCP_PRONUNCIATION_MODEL=small
export MCP_PRONUNCIATION_MODEL=medium

可用选项：tiny、tiny.en、base、base.en、small、small.en、medium、medium.en、large-v3、large-v3-turbo。仅用于英语时，同等大小的 .en 变体速度更快、准确度更高。

如果可用，会自动检测 GPU（CUDA 12 + cuDNN 9）；否则使用 CPU 并进行 int8 量化。

缓存位置

默认情况下，Whisper 权重缓存在 ~/.cache/huggingface/hub/。使用 HF_HUB_CACHE 覆盖：

export HF_HUB_CACHE=/path/to/cache

启动预加载

默认情况下，MCP 握手开始后，服务端会在后台预加载 Whisper 模型。对于只需要发现工具、不应下载模型的注册表检查、Docker 冒烟测试或其他环境，请设置 MCP_PRONUNCIATION_PRELOAD=0：

export MCP_PRONUNCIATION_PRELOAD=0

临时录音

录音会保存为临时 WAV 文件，以便 assess 检查最近一次录音。默认情况下，服务端进程退出时会删除这些文件：

export MCP_PRONUNCIATION_AUDIO_RETENTION=session

如果希望临时录音保留在磁盘上以供手动检查，请设置 MCP_PRONUNCIATION_AUDIO_RETENTION=keep。

麦克风与自动停止控制

默认情况下，服务端使用系统默认麦克风。原生 sounddevice 录音会在检测到 1.5 秒静音后停止。WSL2 通过 Windows PowerShell 录音，可能会一直等待到请求的时长结束，因此请使用较短的 duration 值进行快速语音检查。你可以覆盖原生录音行为：

# Use a specific input device index or name from the `check_mic` tool
export MCP_PRONUNCIATION_INPUT_DEVICE=1

# Options: low, normal, high
# high helps soft speakers; low is better in noisy rooms
export MCP_PRONUNCIATION_VAD_SENSITIVITY=high

# Seconds of silence before auto-stop, clamped to 0.3-5.0
export MCP_PRONUNCIATION_SILENCE_DURATION=2.0

运行 check_mic 可查看默认输入设备、可用设备索引和 当前启用的 VAD 设置。

MCP 客户端中的模型覆盖

# Codex CLI
codex mcp add --env MCP_PRONUNCIATION_MODEL=small.en pronunciation -- uvx mcp-server-pronunciation

# Claude Code
claude mcp add pronunciation -e MCP_PRONUNCIATION_MODEL=small.en -- uvx mcp-server-pronunciation

音素分析附加功能

安装 mcp-server-pronunciation[phoneme] 可启用基于 wav2vec2 的 CTC 强制对齐。它会验证用户实际发出的参考词语，而不受 Whisper 经语言模型加权的解码器改写结果影响，因此罕见专有名词和领域术语不再被误判为发音错误。首次运行时，附加功能会将约 360 MB 的权重下载到 ~/.cache/torch/hub/（可通过 TORCH_HOME 修改存储位置）。默认仅使用 CPU 推理，并会在运行时量化为 int8（约占用 95 MB RAM）。

未安装附加功能时，assess / practice 仍会运行完整流程，只是不执行强制对齐步骤：你仍可获得与 Whisper 假设结果进行 Needleman-Wunsch 词语对齐、CMUdict 音素序列差异、学习者档案提示和韵律分析。

平台支持

平台	录音方式	状态
macOS	sounddevice（内置 PortAudio）	支持
Linux	sounddevice（需要 libportaudio2）	支持
Windows	sounddevice（内置 PortAudio）	支持
WSL2	PowerShell MCI（winmm.dll）	支持

WSL2 说明：WSLg 的 PulseAudio 不会转发来自 Windows 主机的麦克风音频。此服务会自动检测 WSL2，并改为通过 Windows 端的 PowerShell 录音。WSL2 录音可能会等待完整的指定时长，而不是在静音时自动停止。

故障排查

首先运行 uvx mcp-server-pronunciation doctor

它会检查 PortAudio、输入设备、Whisper 模型缓存、发音资源、可选的强制对齐依赖、可用磁盘空间和 Python 版本。遇到问题时都可以运行它。

Linux 上 sounddevice 导入失败

你缺少 libportaudio2。请参阅上面的安装部分。安装后：

uvx mcp-server-pronunciation doctor

未捕获音频 / 录音为空

• macOS：系统设置 → 隐私与安全性 → 麦克风。为启动 MCP 客户端的应用授予访问权限，例如 Codex CLI、Claude Desktop 或 Claude Code。
• Linux：通过 pavucontrol（PulseAudio）或 pw-cli list-objects（PipeWire）检查输入音量。在仅使用 PipeWire 的系统上，请安装 pipewire-alsa。
• WSL2：在 Windows 设置 → 声音 → 输入中测试麦克风。此服务通过 Windows 录音，而不是通过 WSLg。

首次运行较慢

首次使用时会下载 Whisper 模型（base.en 约 150 MB）。可以预先下载一次：

uvx mcp-server-pronunciation pull-model base.en

后续运行会复用缓存的权重。如果启动仍然较慢，可以尝试 MCP_PRONUNCIATION_MODEL=tiny.en。

macOS 上的 Claude Desktop：spawn uvx ENOENT

Claude Desktop 会在仅限 GUI 的环境中启动 MCP 服务，该环境的 PATH 中没有 ~/.local/bin。请在配置中使用 uvx 的绝对路径（/Users/YOU/.local/bin/uvx，或 which uvx 显示的路径）。

已知限制

• 这是一个稳定版软件包，但发音和韵律反馈仍属于实验性辅导信号。仍可能出现错误、运行时异常、不准确的反馈以及特定平台的录音问题。
• 发音评分是辅导信号，不代表标准化考试成绩、临床判断或与母语者水平等同的评定。
• Whisper 仍可能误听罕见姓名、领域术语、较短的音频片段、音量较低的音频或口音较重的语音。可选的 [phoneme] 扩展可以减少一些参考句误报，但无法完全消除。
• 韵律反馈基于启发式方法。音频存在噪声、语句非常短、出现气声、语音重叠或录音被截断时，音高跟踪可能不可靠。
• 学习者档案提示有意采用基于规则的方式。当前软件包包含韩语为母语的提示，但可能漏掉错误、因 ASR 错误而过度触发，应视为有针对性的练习辅助。欢迎为其他母语档案贡献内容。
• 首次设置时可能会下载模型或发音资源。在实时会话中依赖该服务之前，请先运行 doctor 和 pull-model。
• 临时 WAV 录音会写入系统临时目录，以便评估最近一次录音。默认情况下，服务退出时会删除这些文件。若要之后检查录音，请设置 MCP_PRONUNCIATION_AUDIO_RETENTION=keep。

基准测试状态

本项目正朝着基于基准测试的评分方向发展。计划中的公开基准测试工作记录在 ROADMAP.md 中，测试方法见 docs/TESTING.md，当前的基准测试辅助工具文档见 docs/BENCHMARKS.md。首选候选数据集是 Speechocean762，因为它采用宽松的 CC BY 4.0 许可证，并提供多级专家发音评分。L2-ARCTIC 可用于音素错误和学习者档案研究检查，包括韩语为母语的子集审查，但其非商业许可证意味着它应保持为可选项，并与默认版本声明分开。

发布状态

源代码仓库是公开的。PyPI、GitHub Release 和 MCP Registry 的发布步骤记录在 docs/PUBLICATION.md 中。

隐私

• 所有音频处理都在你的计算机上本地进行。
• 录音是系统临时目录（$TMPDIR）下的临时 .wav 文件，服务退出时会被删除，除非设置了 MCP_PRONUNCIATION_AUDIO_RETENTION=keep。
• Whisper 模型在本地运行，不会向任何外部服务发送音频数据。
• 安装可选的 [phoneme] 扩展后，wav2vec2 强制对齐器也会在本地运行。权重会从 PyTorch Hub 下载一次。
• 无遥测，无分析。除首次下载模型权重外（Whisper 权重来自 Hugging Face，wav2vec2 权重来自 PyTorch Hub），不会进行网络调用。

开发

git clone https://github.com/JuhongPark/mcp-server-pronunciation.git
cd mcp-server-pronunciation
uv sync --extra dev
uv run pytest -v
uv run ruff check .
uv run ruff format --check .

若要使用可选的 wav2vec2 强制对齐路径进行开发，也请安装 phoneme 扩展：

uv sync --extra dev --extra phoneme

支持

问题反馈：https://github.com/JuhongPark/mcp-server-pronunciation/issues

许可证

MIT。请参阅 LICENSE。

第三方组件（均为 MIT 或宽松许可证）：

• faster-whisper — MIT
• OpenAI Whisper models — MIT
• CTranslate2 — MIT
• sounddevice — MIT
• PortAudio — MIT
• cmudict — BSD
• g2p-en — Apache 2.0
• librosa — ISC
• 可选（[phoneme] 扩展）：PyTorch — BSD、torchaudio — BSD、wav2vec2 weights — MIT