Whisper MCP — Transcrição com Diarização
Antonio-2022/whisper-mcp
Transcrição offline com diarização de falantes para Macs Apple Silicon
Ver no GitHubServidor MCP local para transcrição de áudio de alta qualidade em Apple Silicon, com detecção automática de idioma e identificação de falantes via diarização. Utiliza MLX-Whisper para processamento acelerado por Metal e suporta arquivos grandes através de chunking automático.
Instalação
npx convez-ai Antonio-2022/whisper-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Transcrever entrevistas e podcasts com identificação de quem fala
- Processar reuniões e calls longas (> 30 min) localmente
- Converter palestras e seminários em texto com rótulos de palestrantes
- Integrar transcrição privada em workflows Claude
Veredito

Solução robusta para transcrição local em Apple Silicon com diarização, ideal para quem precisa privacidade e quer evitar APIs externas. Requer setup prévio (HF token, ffmpeg) e funciona bem como daemon persistente via launchd, mas é exclusivo para macOS com chip Apple.
README
A tradução para o português deste README ainda está na fila.
whisper-mcp
Local-only MCP server for high-quality audio transcription on Apple Silicon (MLX).
Features
- Fast transcription via mlx-whisper (
whisper-large-v3-turbo, Metal/MLX) - Automatic language detection — 30-second sample pass when language not specified
- Chunked transcription for recordings > 30 minutes (splits into 30-min WAV chunks, merges results)
- Speaker diarization via
pyannote.audio3.x on MPS (requires HuggingFace token) - Background job queue with polling — survives MCP client timeouts
Requirements
- Apple Silicon Mac (M1/M2/M3/M4)
- Python 3.11+ (via pyenv)
- ffmpeg (
brew install ffmpeg)
Installation
pip install -r requirements.txt
Configuration
HuggingFace token (for speaker diarization)
- Accept model terms at https://huggingface.co/pyannote/speaker-diarization-3.1
- Create a read token at https://huggingface.co/settings/tokens
- Store locally — never commit this file:
mkdir -p ~/.config/whisper-mcp
echo 'HF_TOKEN=hf_YOUR_TOKEN_HERE' > ~/.config/whisper-mcp/.env
chmod 600 ~/.config/whisper-mcp/.env
launchd service (macOS)
cp launchd/com.antonio.whisper-mcp.plist.template ~/Library/LaunchAgents/com.antonio.whisper-mcp.plist
# Edit the plist and replace ${HF_TOKEN} with your actual token
# Optionally adjust the Python path to match your pyenv version
launchctl load ~/Library/LaunchAgents/com.antonio.whisper-mcp.plist
Claude Code MCP configuration
Add to your ~/.claude/settings.json under mcpServers:
{
"mcpServers": {
"whisper": {
"type": "http",
"url": "http://127.0.0.1:8765/mcp"
}
}
}
Claude Code skill (optional)
Install the /transcribe skill for guided, high-quality transcriptions:
mkdir -p ~/.claude/skills/transcribe
cp skills/transcribe.md ~/.claude/skills/transcribe/SKILL.md
Then use /transcribe in Claude Code — it handles language detection, diarization, polling, and output formatting automatically.
MCP Tools
| Tool | Description |
|---|---|
start_transcribe | Start a background job — returns job_id immediately |
get_transcribe | Poll a job for status and result |
transcribe | Start + wait up to N seconds inline (use for short files) |
warm_model | Pre-load model to avoid cold-start latency (~5-15s) |
status | Daemon health, active jobs, config, and the diarization stack/ABI block (cheap, no model load) |
diagnostics | Actively load the pyannote pipeline and report whether diarization is healthy — run before a long transcription |
Key parameters for start_transcribe
| Parameter | Type | Description |
|---|---|---|
path | string | Absolute path to local audio file (m4a, mp3, wav, mp4, opus…) |
language | string | null | BCP-47 code e.g. "ru", "de", "en". Omit to auto-detect. Always set if known. |
task | string | "transcribe" (default) or "translate" (→ English) |
diarize | bool | true to identify speakers. Requires HF_TOKEN. |
num_speakers | int | null | Known speaker count — improves diarization accuracy |
Result fields (when status == "done")
| Field | Description |
|---|---|
text | Plain transcript, no speaker labels |
transcript_with_speakers | Speaker-labeled blocks (present when diarize=true) |
speakers | List of speaker IDs e.g. ["SPEAKER_00", "SPEAKER_01"] |
diarization_status | ok / degraded / failed / empty — present whenever diarize=true, even on a successful transcript, so a silent fallback to plain text is never invisible |
warning | Human-readable note when diarization failed or degraded (e.g. collapsed to one speaker) |
language | Detected/used language code |
audio_duration_s | Total audio duration in seconds |
Typical completion times
| Audio length | Warm model | Cold model |
|---|---|---|
| 10 min | ~30s | ~60s |
| 30 min | ~90s | ~3min |
| 1 hour | ~3min | ~6min |
| 3 hours | ~10min | ~18min (+3-5min diarization) |
Diarization stack (ABI-locked) & troubleshooting
Speaker diarization depends on an ABI-matched set of torch / torchaudio /
torchvision / pyannote.audio. These are hard-pinned in requirements.txt on purpose:
torch==2.8.0 torchaudio==2.8.0 torchvision==0.23.0 pyannote.audio==3.4.0
If a transitive upgrade bumps torch without torchaudio (torchvision self-pins torch
and is the usual culprit, dragging it toward 2.11), the compiled extensions mismatch
(libtorchaudio.so: Symbol not found … c10::MessageLogger), pyannote fails to load, and
the server falls back to a plain, speaker-less transcript. Do not loosen the pins to >=.
This used to fail silently. It no longer does:
diagnosticsactively loads the pipeline and returns{"ok": true|false, "detail": …}plus the live version matrix. Run it before a long transcription.statuscarries a cheapdiarizationblock (version matrix + ABI match, no model load).- A failed/degraded diarization now sets
diarization_status+warningon the job result even when the transcript itself succeeded. _load_diarize_pipelinepre-checks the torch/torchaudio match and raises an actionable error instead of the cryptic symbol-not-found.
To re-pin after any environment change and restart:
pip install -r requirements.txt
launchctl kickstart -k gui/$(id -u)/com.antonio.whisper-mcp
# confirm: diagnostics() → {"ok": true, "detail": "diarization ready"}
Note: on a mono mixdown of a phone/online call with two similar voices (e.g. both female), pyannote can collapse nearly all speech onto one speaker even with
num_speakers=2. That now surfaces asdiarization_status: "degraded"— attribute speakers by content/role in that case.
Logs
tail -f ~/Library/Logs/whisper-mcp.log
Rotating log, max 10 MB × 3 files.