{
  "markdown": "# mcp-server-pronunciation\n\n[![mcp-server-pronunciation MCP server](https://glama.ai/mcp/servers/JuhongPark/mcp-server-pronunciation/badges/score.svg)](https://glama.ai/mcp/servers/JuhongPark/mcp-server-pronunciation)\n\n<!-- mcp-name: io.github.JuhongPark/pronunciation -->\n\n> **Accuracy and safety notice**\n>\n> This project is a local language-learning practice tool. It may contain bugs,\n> runtime errors, inaccurate transcripts, inaccurate pronunciation feedback, or\n> platform-specific recording issues. Pronunciation feedback is a coaching\n> signal, not a standardized-test, clinical, employment, or high-stakes\n> assessment. Review outputs carefully before relying on them. See\n> [DISCLAIMER.md](DISCLAIMER.md).\n\nAn 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.\n\nBuilt 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`](https://github.com/SYSTRAN/faster-whisper) on-device, and never leaves your machine.\n\n`mcp-name: io.github.JuhongPark/pronunciation`\n\n## Why\n\nVoice 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.\n\n## Features\n\n- **Voice conversation** with your MCP assistant. Speak, auto-stop on silence, then let the assistant read your transcript and respond.\n- **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).\n- **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.\n- **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.\n- **Inline English feedback in conversation**: pronunciation, grammar (common irregular-verb errors), and fluency (pace + long pauses).\n- **Drill mode** (`practice`, `quick_practice`, `retry`) for focused sentence practice.\n- **Local-only**: Whisper model runs on your machine, audio never leaves it.\n- **Cross-platform**: macOS, Linux, Windows, and WSL2 (recording auto-routes through Windows).\n- **Fast startup**: lazy imports + background model pre-load keep the MCP handshake under a second.\n\n## Requirements\n\n- Python 3.11+\n- A working microphone\n- ~150 MB disk space for the default Whisper model (`base.en`)\n- Additional ~360 MB if you install the optional `[phoneme]` extra (wav2vec2 weights for forced alignment)\n- MCP spec: targets `2025-06-18` via the official Python SDK (`mcp>=1.2`)\n\n## Installation\n\n### Stable release\n\nInstall the latest stable release:\n\n```bash\nuvx mcp-server-pronunciation\n```\n\nFor pip users:\n\n```bash\npip install mcp-server-pronunciation\n```\n\nTo pin this release explicitly:\n\n```bash\nuvx mcp-server-pronunciation@0.3.0\n```\n\nRun `doctor` before relying on the server in a live session:\n\n```bash\nmcp-server-pronunciation doctor\n```\n\n### General install commands\n\n```bash\n# Recommended: uvx (no global install, cached between runs)\nuvx mcp-server-pronunciation\n\n# Or install as a uv tool\nuv tool install mcp-server-pronunciation\n\n# Or pip\npip install mcp-server-pronunciation\n\n# Optional: forced-alignment upgrade for Whisper-bias mitigation + tighter\n# phoneme-level feedback. Adds ~200 MB of torch CPU wheels.\npip install 'mcp-server-pronunciation[phoneme]'\n```\n\n### Linux: install PortAudio first\n\n`sounddevice` ships PortAudio inside the wheel on macOS and Windows, but on Linux you need the system library:\n\n```bash\n# Debian / Ubuntu\nsudo apt-get install libportaudio2\n\n# Fedora / RHEL\nsudo dnf install portaudio\n\n# Arch\nsudo pacman -S portaudio\n\n# PipeWire-only systems may also need\nsudo apt-get install pipewire-alsa\n```\n\n### First-time check\n\nBefore wiring the server into an MCP client, run the preflight:\n\n```bash\nuvx mcp-server-pronunciation doctor\n```\n\nOptional — pre-download the Whisper model (~150 MB) so the first call is instant:\n\n```bash\nuvx mcp-server-pronunciation pull-model base.en\n```\n\n## Add to your MCP client\n\n### Codex CLI\n\n```bash\ncodex mcp add pronunciation -- uvx mcp-server-pronunciation\n```\n\n### Claude Code\n\n```bash\nclaude mcp add pronunciation -- uvx mcp-server-pronunciation\n```\n\n### Claude Desktop\n\nEdit `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"pronunciation\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-pronunciation\"]\n    }\n  }\n}\n```\n\nOn macOS, if Claude Desktop can't find `uvx` (`spawn uvx ENOENT`), use an absolute path. Find it with `which uvx` in your terminal.\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"pronunciation\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-pronunciation\"]\n    }\n  }\n}\n```\n\n### VS Code (with MCP support)\n\nAdd to `.vscode/mcp.json` or your user settings:\n\n```json\n{\n  \"servers\": {\n    \"pronunciation\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-pronunciation\"]\n    }\n  }\n}\n```\n\n## Usage Examples\n\n### 1. Voice chat with feedback\n\n> **You**: \"Let's have a voice chat. I'll ask you about the weekend. Use the converse tool.\"\n>\n> **Assistant** (calls `converse`): *records your speech, transcribes it, notes that you said \"buyed\" instead of \"bought\"*\n>\n> **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.\"\n\n### 2. Drill a specific sentence\n\n> **You**: \"Give me a sentence to practice with 'th' sounds.\"\n>\n> **Assistant** (calls `suggest_sentence` with `focus=th`): \"Try this: *The three brothers thought thoroughly about their future.*\"\n>\n> **You**: \"Record me reading it.\"\n>\n> **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).*\n\n### 3. Retry after feedback\n\n> **You**: \"Let me try again.\"\n>\n> **Assistant** (calls `retry`): *re-records the same target sentence and compares*\n\n## Tools\n\n| Tool | Purpose |\n|---|---|\n| **`converse`** | **Primary**. Record + transcribe + quick feedback + assistant guidance for natural voice-chat-with-coaching. |\n| `practice` | Drill mode: record user reading a specific reference sentence, return detailed assessment. |\n| `quick_practice` | Pick a random sentence (by phoneme focus + difficulty) and drill it. |\n| `retry` | Re-record the last sentence and compare the new attempt against the previous one. |\n| `open_voice_panel` | Open the MCP Apps voice panel when the client supports embedded UI. |\n| `analyze_uploaded_audio` | Analyze WAV audio uploaded by the voice panel and store it as the latest voice capture. |\n| `start_voice_capture` | Start recording in the background and return a session id immediately. |\n| `voice_capture_status` | Check whether a background capture is recording, analyzing, done, cancelled, or failed. |\n| `wait_for_voice_capture` | Wait for a background capture to finish and return transcript + feedback. |\n| `latest_voice_capture` | Return the most recent background voice capture result. |\n| `cancel_voice_capture` | Mark a background capture as cancelled before analysis starts. |\n| `suggest_sentence` | Return a practice sentence without recording. |\n| `record` | Record audio and save a WAV file (raw, no analysis). |\n| `assess` | Assess the last recording (or a specified WAV) without re-recording. When given a reference, runs the full drill pipeline (alignment, phoneme diff, learner-profile hints, prosody). |\n| `check_mic` | List available audio input devices. |\n\nTools that assess speech also return structured MCP output with `transcript`,\n`clarity_pct`, `speaking_rate_wpm`, `top_issue`, `next_action`,\n`retry_comparison`, the full machine-readable `assessment`, and the rendered\n`report_markdown`. MCP clients can use the structured result to offer a retry,\nsurface the top issue, or build a richer practice UI without parsing Markdown.\n\n### Visible voice-capture workflow\n\nFor MCP clients without an embedded voice UI, use the background capture tools\nto keep the user informed:\n\n```text\nstart_voice_capture(duration=8, mode=\"conversation\")\nvoice_capture_status(session_id)\nwait_for_voice_capture(session_id, timeout=30)\nlatest_voice_capture()\n```\n\nThe status response includes `recording`, `analyzing`, `done`, `error`, or\n`cancelled`, plus elapsed time, transcript, clarity, speaking rate, feedback\nmarkdown, and the full structured assessment when available. On WSL2, keep\n`duration` short because PowerShell recording may wait for the full requested\nduration before analysis begins.\n\n### MCP Apps voice panel\n\nClients that support MCP Apps can call `open_voice_panel` to render the\n`ui://pronunciation/voice-panel` resource. The panel requests browser\nmicrophone access, records locally in the browser, uploads a WAV clip through\n`analyze_uploaded_audio`, and displays the returned transcript and feedback.\n\nThe uploaded clip is stored in the same voice session registry as MCP-only\nrecordings, so assistants can call `latest_voice_capture` after the panel\nfinishes and respond to both the development note and the pronunciation\nfeedback. Clients without MCP Apps support should use the visible\nvoice-capture workflow above.\n\n## Prompt Shortcuts\n\nMCP clients that expose server prompts can start common workflows directly:\n\n| Prompt | Purpose |\n|---|---|\n| `start_voice_chat` | Start a local voice conversation with light feedback. |\n| `daily_practice` | Run a short suggested-sentence practice loop. |\n| `practice_focus` | Start a drill for a chosen focus and difficulty. |\n| `troubleshoot_mic` | Inspect microphone devices and recording settings. |\n\n## Configuration\n\n### Whisper model\n\nSet `MCP_PRONUNCIATION_MODEL` to pick a different model size:\n\n```bash\n# Default — fast, English-only (~150 MB)\nexport MCP_PRONUNCIATION_MODEL=base.en\n\n# Smaller / faster (~75 MB)\nexport MCP_PRONUNCIATION_MODEL=tiny.en\n\n# More accurate (~470 MB)\nexport MCP_PRONUNCIATION_MODEL=small.en\n\n# Multilingual options (larger)\nexport MCP_PRONUNCIATION_MODEL=small\nexport MCP_PRONUNCIATION_MODEL=medium\n```\n\nAvailable: `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.\n\nGPU (CUDA 12 + cuDNN 9) is auto-detected when available; otherwise runs on CPU with int8 quantization.\n\n### Cache location\n\nBy default Whisper weights are cached in `~/.cache/huggingface/hub/`. Override with `HF_HUB_CACHE`:\n\n```bash\nexport HF_HUB_CACHE=/path/to/cache\n```\n\n### Startup preload\n\nBy default the server preloads the Whisper model in the background after the\nMCP handshake starts. Set `MCP_PRONUNCIATION_PRELOAD=0` for registry\ninspection, Docker smoke tests, or other environments that only need tool\ndiscovery and should avoid model downloads:\n\n```bash\nexport MCP_PRONUNCIATION_PRELOAD=0\n```\n\n### Temporary recordings\n\nRecordings are written as temporary WAV files so `assess` can inspect the last\nrecording. By default they are removed when the server process exits:\n\n```bash\nexport MCP_PRONUNCIATION_AUDIO_RETENTION=session\n```\n\nSet `MCP_PRONUNCIATION_AUDIO_RETENTION=keep` if you want temporary recordings\nto remain on disk for manual inspection.\n\n### Microphone and auto-stop controls\n\nBy default the server uses your system default microphone. Native\n`sounddevice` recording stops after 1.5 seconds of detected silence. WSL2\nrecords through Windows PowerShell and may wait for the full requested\nduration, so use a short `duration` value for quick voice checks. You can\noverride native recording behavior:\n\n```bash\n# Use a specific input device index or name from the `check_mic` tool\nexport MCP_PRONUNCIATION_INPUT_DEVICE=1\n\n# Options: low, normal, high\n# high helps soft speakers; low is better in noisy rooms\nexport MCP_PRONUNCIATION_VAD_SENSITIVITY=high\n\n# Seconds of silence before auto-stop, clamped to 0.3-5.0\nexport MCP_PRONUNCIATION_SILENCE_DURATION=2.0\n```\n\nRun `check_mic` to see the default input device, available device indexes, and\nthe active VAD settings.\n\n### Model override in MCP clients\n\n```bash\n# Codex CLI\ncodex mcp add --env MCP_PRONUNCIATION_MODEL=small.en pronunciation -- uvx mcp-server-pronunciation\n\n# Claude Code\nclaude mcp add pronunciation -e MCP_PRONUNCIATION_MODEL=small.en -- uvx mcp-server-pronunciation\n```\n\n### Phoneme analysis extras\n\nInstalling `mcp-server-pronunciation[phoneme]` enables wav2vec2-based CTC forced alignment. It verifies which reference words the user acoustically produced, regardless of how Whisper's language-model-weighted decoder rewrote them — so rare proper nouns and domain terms no longer surface as false mispronunciations. On first run the extra downloads ~360 MB of weights into `~/.cache/torch/hub/` (override via `TORCH_HOME`). Inference is CPU-only by default and runtime-quantized to int8 (~95 MB RAM).\n\nWithout the extra, `assess` / `practice` still run the full pipeline except for the forced-alignment step: you get Needleman-Wunsch word alignment against the Whisper hypothesis, CMUdict phoneme-sequence diff, learner-profile hints, and prosody.\n\n## Platform Support\n\n| Platform | Recording method | Status |\n|----------|------------------|--------|\n| macOS | sounddevice (bundled PortAudio) | Supported |\n| Linux | sounddevice (needs `libportaudio2`) | Supported |\n| Windows | sounddevice (bundled PortAudio) | Supported |\n| WSL2 | PowerShell MCI (winmm.dll) | Supported |\n\n**WSL2 note**: WSLg's PulseAudio does not forward microphone audio from the Windows host. This server detects WSL2 automatically and records through PowerShell on the Windows side instead. WSL2 recording may wait for the full requested duration instead of auto-stopping on silence.\n\n## Troubleshooting\n\n### `uvx mcp-server-pronunciation doctor` is your first stop\n\nIt reports on PortAudio, input devices, Whisper model cache, pronunciation\nresources, optional forced-alignment dependencies, free disk space, and Python\nversion. Run it whenever something feels off.\n\n### `sounddevice` import fails on Linux\n\nYou're missing `libportaudio2`. See the install section above. After installing:\n\n```bash\nuvx mcp-server-pronunciation doctor\n```\n\n### No audio captured / empty recording\n\n- **macOS**: System Settings → Privacy & Security → Microphone. Grant access to the app that launched your MCP client, such as Codex CLI, Claude Desktop, or Claude Code.\n- **Linux**: Check `pavucontrol` (PulseAudio) or `pw-cli list-objects` (PipeWire) for input levels. On PipeWire-only systems, install `pipewire-alsa`.\n- **WSL2**: Test your mic in Windows Settings → Sound → Input. The server records through Windows, not through WSLg.\n\n### First run is slow\n\nThe Whisper model downloads on first use (~150 MB for `base.en`). Pre-download it once:\n\n```bash\nuvx mcp-server-pronunciation pull-model base.en\n```\n\nSubsequent runs reuse the cached weights. If startup still feels slow, try `MCP_PRONUNCIATION_MODEL=tiny.en`.\n\n### Claude Desktop on macOS: `spawn uvx ENOENT`\n\nClaude Desktop launches MCP servers from a GUI-only environment without `~/.local/bin` on PATH. Use the absolute path to `uvx` in your config (`/Users/YOU/.local/bin/uvx` or wherever `which uvx` reports).\n\n## Known Limitations\n\n- This is a stable package release, but the pronunciation and prosody feedback\n  remain experimental coaching signals. Bugs, runtime errors, inaccurate\n  feedback, and platform-specific recording issues can still occur.\n- Pronunciation scores are coaching signals, not standardized-test, clinical, or native-speaker-equivalence judgments.\n- Whisper can still mishear rare names, domain terms, short clips, quiet audio, or heavily accented speech. The optional `[phoneme]` extra reduces some reference-sentence false positives but does not eliminate them.\n- Prosody feedback is heuristic. Pitch tracking can be unreliable with noisy audio, very short utterances, vocal fry, overlapping speech, or clipped recordings.\n- Learner-profile hints are intentionally rule-based. The current package includes Korean-L1 hints, but they can miss errors, over-trigger on ASR mistakes, and should be treated as targeted practice aids. Contributions for additional L1 profiles are welcome.\n- First-time setup may download model or pronunciation resources. Run `doctor` and `pull-model` before relying on the server in a live session.\n- Temporary WAV recordings are written under the system temp directory so that the last recording can be assessed. By default they are removed when the server exits. Set `MCP_PRONUNCIATION_AUDIO_RETENTION=keep` if you want to inspect them later.\n\n## Benchmark Status\n\nThis project is moving toward benchmark-backed scoring. Planned public benchmark work is tracked in [ROADMAP.md](ROADMAP.md), the testing methodology lives in [docs/TESTING.md](docs/TESTING.md), and the current benchmark helper docs live in [docs/BENCHMARKS.md](docs/BENCHMARKS.md). The primary candidate is Speechocean762 because it has a permissive CC BY 4.0 license and multi-level expert pronunciation scores. L2-ARCTIC is useful for phone-error and learner-profile research checks, including Korean-L1 subset review, but its non-commercial license means it should remain optional and separate from default release claims.\n\n## Publication Status\n\nThe source repository is public. PyPI, GitHub Release, and MCP Registry\npublication steps are tracked in [docs/PUBLICATION.md](docs/PUBLICATION.md).\n\n## Privacy\n\n- All audio processing happens **locally** on your machine.\n- Recordings are temporary `.wav` files under your system temp directory (`$TMPDIR`) and are removed when the server exits unless `MCP_PRONUNCIATION_AUDIO_RETENTION=keep` is set.\n- The Whisper model runs locally — no audio data is sent to any external service.\n- When the optional `[phoneme]` extra is installed, the wav2vec2 forced aligner also runs locally. Weights are downloaded once from the PyTorch Hub.\n- No telemetry. No analytics. No network calls except the one-time model weight downloads (Whisper from Hugging Face, wav2vec2 from PyTorch Hub).\n\n## Development\n\n```bash\ngit clone https://github.com/JuhongPark/mcp-server-pronunciation.git\ncd mcp-server-pronunciation\nuv sync --extra dev\nuv run pytest -v\nuv run ruff check .\nuv run ruff format --check .\n```\n\nTo work on the optional wav2vec2 forced-alignment path, install the phoneme\nextra as well:\n\n```bash\nuv sync --extra dev --extra phoneme\n```\n\n## Support\n\nIssues: https://github.com/JuhongPark/mcp-server-pronunciation/issues\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\nThird-party components (all MIT / permissive):\n- [`faster-whisper`](https://github.com/SYSTRAN/faster-whisper) — MIT\n- [OpenAI Whisper models](https://github.com/openai/whisper) — MIT\n- [CTranslate2](https://github.com/OpenNMT/CTranslate2) — MIT\n- [`sounddevice`](https://python-sounddevice.readthedocs.io/) — MIT\n- [PortAudio](http://www.portaudio.com/) — MIT\n- [`cmudict`](https://pypi.org/project/cmudict/) — BSD\n- [`g2p-en`](https://github.com/Kyubyong/g2p) — Apache 2.0\n- [`librosa`](https://librosa.org/) — ISC\n- Optional (`[phoneme]` extra): [PyTorch](https://pytorch.org/) — BSD, [torchaudio](https://pytorch.org/audio/) — BSD, [wav2vec2 weights](https://github.com/facebookresearch/fairseq) — MIT\n",
  "bytes": 20285,
  "sha": "b9d81c79120e94e33db43ae5140f714a35959247986ab89579a5ddab0a90ee67",
  "repo_slug": "juhongpark/mcp-server-pronunciation",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_juhongpark_pronunciation_81264873/readme"
}