Pronunciation & Voice Coach

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:

uvx mcp-server-pronunciation

For pip users:

pip install mcp-server-pronunciation

To pin this release explicitly:

uvx mcp-server-pronunciation@0.3.0

Run doctor before relying on the server in a live session:

mcp-server-pronunciation doctor

General install commands

# 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: install PortAudio first

sounddevice ships PortAudio inside the wheel on macOS and Windows, but on Linux you need the system library:

# 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

First-time check

Before wiring the server into an MCP client, run the preflight:

uvx mcp-server-pronunciation doctor

Optional — pre-download the Whisper model (~150 MB) so the first call is instant:

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

Add to your MCP client

Codex CLI

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

Claude Code

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

Claude Desktop

Edit claude_desktop_config.json:

{

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

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:

{

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

VS Code (with MCP support)

Add to .vscode/mcp.json or your user settings:

{

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

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"*

Assistant: "Oh nice — what kind of apples did you buy? And by the way, the past tense of 'buy' is 'bought' — small thing, but I noticed it."

2. Drill a specific sentence

You: "Give me a sentence to practice with 'th' sounds."

Assistant (calls suggest_sentence with focus=th): "Try this: *The three brothers thought thoroughly about their future.*"

You: "Record me reading it."

Assistant (calls practice with that reference): *returns an alignment table (match / sub / ins / del) with per-word acoustic confidence when the [phoneme] extra is installed, phoneme-level issues with expected vs produced IPA, learner-profile hints when applicable, minimal-pair drills, and prosody notes (word stress, final-rise intonation, intra-clause pauses).*

3. Retry after feedback

You: "Let me try again."

Assistant (calls retry): *re-records the same target sentence and compares*

Tools

Tools that assess speech also return structured MCP output with transcript, clarity_pct, speaking_rate_wpm, top_issue, next_action, retry_comparison, the full machine-readable assessment, and the rendered report_markdown. MCP clients can use the structured result to offer a retry, surface the top issue, or build a richer practice UI without parsing Markdown.

Visible voice-capture workflow

For MCP clients without an embedded voice UI, use the background capture tools to keep the user informed:

start_voice_capture(duration=8, mode="conversation")

voice_capture_status(session_id) wait_for_voice_capture(session_id, timeout=30) latest_voice_capture()

The status response includes recording, analyzing, done, error, or cancelled, plus elapsed time, transcript, clarity, speaking rate, feedback markdown, and the full structured assessment when available. On WSL2, keep duration short because PowerShell recording may wait for the full requested duration before analysis begins.

MCP Apps voice panel

Clients that support MCP Apps can call open_voice_panel to render the ui://pronunciation/voice-panel resource. The panel requests browser microphone access, records locally in the browser, uploads a WAV clip through analyze_uploaded_audio, and displays the returned transcript and feedback. Uploaded audio must be a readable 16-bit PCM RIFF/WAVE file with mono or stereo audio at 8-48 kHz, no larger than 20 MB and no longer than 120 seconds.

The uploaded clip is stored in the same voice session registry as MCP-only recordings, so assistants can call latest_voice_capture after the panel finishes and respond to both the development note and the pronunciation feedback. Clients without MCP Apps support should use the visible voice-capture workflow above.

Prompt Shortcuts

MCP clients that expose server prompts can start common workflows directly:

Configuration

Whisper model

Set MCP_PRONUNCIATION_MODEL to pick a different model size:

# 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

Available: tiny, tiny.en, base, base.en, small, small.en, medium, medium.en, large-v3, large-v3-turbo. For English-only use, the .en variants are faster and more accurate at a given size.

GPU (CUDA 12 + cuDNN 9) is auto-detected when available; otherwise runs on CPU with int8 quantization.

Cache location

By default Whisper weights are cached in ~/.cache/huggingface/hub/. Override with HF_HUB_CACHE:

export HF_HUB_CACHE=/path/to/cache

Startup preload

By default the server preloads the Whisper model in the background after the MCP handshake starts. Set MCP_PRONUNCIATION_PRELOAD=0 for registry inspection, Docker smoke tests, or other environments that only need tool