JuhongPark/mcp-server-pronunciation

> **Accuracy and safety notice**
>
> This project is a local language-learning practice tool. It may contain bugs,
> runtime errors, inaccurate transcripts, inaccurate pronunciation feedback, or
> platform-specific recording issues. Pronunciation feedback is a coaching
> signal, not a standardized-test, clinical, employment, or high-stakes
> assessment. Review outputs carefully before relying on them. See
> DISCLAIMER.md.
An MCP (Model Context Protocol) server that lets you **talk to your MCP assistant by voice while getting English pronunciation, grammar, and fluency feedback** in the same turn. Use it for casual voice chat with light coaching, or switch to drill mode when you want to practice a specific sentence.
Built for Codex CLI, Claude Desktop, Claude Code, Cursor, VS Code, and other MCP clients. Everything runs locally — audio is captured with your mic, transcribed by faster-whisper on-device, and never leaves your machine.
mcp-name: io.github.JuhongPark/pronunciation
Why
Voice MCP servers today treat speech as a typing replacement. English tutor MCP servers are text-only. This one combines the two: you speak freely, your assistant replies, and feedback on what you just said (pronunciation, grammar, fluency) surfaces inside the same tool call so the assistant can weave it into a natural reply — or stay out of the way when you're just chatting.
Features
- **Voice conversation** with your MCP assistant. Speak, auto-stop on silence, then let the assistant read your transcript and respond.
- **Phoneme-level drill feedback** (when a reference sentence is given): Needleman-Wunsch word alignment, per-word expected vs produced IPA, learner-profile hints, minimal-pair drills, and prosody checks (word stress, final-rise intonation, intra-clause pauses).
- **Extensible learner-profile support**: the current rule pack includes Korean-L1 pronunciation-pattern hints and Korean-language tips. Contributions for additional L1 profiles are welcome.
- **Whisper-bias mitigation** via optional [phoneme] extra: wav2vec2 CTC forced alignment verifies whether the user actually produced each reference word, so rare proper nouns and domain-specific terms that Whisper rewrites toward more common alternatives no longer surface as mispronunciations.
- **Inline English feedback in conversation**: pronunciation, grammar (common irregular-verb errors), and fluency (pace + long pauses).
- **Drill mode** (practice, quick_practice, retry) for focused sentence practice.
- **Local-only**: Whisper model runs on your machine, audio never leaves it.
- **Cross-platform**: macOS, Linux, Windows, and WSL2 (recording auto-routes through Windows).
- **Fast startup**: lazy imports + background model pre-load keep the MCP handshake under a second.
Requirements
- Python 3.11+
- A working microphone
- ~150 MB disk space for the default Whisper model (base.en)
- Additional ~360 MB if you install the optional [phoneme] extra (wav2vec2 weights for forced alignment)
- MCP spec: targets 2025-06-18 via the official Python SDK (mcp>=1.2)
Installation
Stable release
Install the latest stable release:
For pip users:
To pin this release explicitly:
Run doctor before relying on the server in a live session:
General install commands
Linux: install PortAudio first
sounddevice ships PortAudio inside the wheel on macOS and Windows, but on Linux you need the system library:
First-time check
Before wiring the server into an MCP client, run the preflight:
Optional — pre-download the Whisper model (~150 MB) so the first call is instant:
Add to your MCP client
Codex CLI
Claude Code
Claude Desktop
Edit claude_desktop_config.json:
On macOS, if Claude Desktop can't find uvx (spawn uvx ENOENT), use an absolute path. Find it with which uvx in your terminal.
Cursor
Add to ~/.cursor/mcp.json:
VS Code (with MCP support)
Add to .vscode/mcp.json or your user settings:
Usage Examples
1. Voice chat with feedback
> **You**: "Let's have a voice chat. I'll ask you about the weekend. Use the converse tool."
>
> **Assistant** (calls converse): *records your speech, transcribes it, notes that you said "buyed" instead of "bought"*