convez.ai
MCP ServerProdutividadeIntermediário
Antonio-2022

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 GitHub
InicialPluginScore · de 0 a 100

Servidor 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-mcp

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

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.audio 3.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)

  1. Accept model terms at https://huggingface.co/pyannote/speaker-diarization-3.1
  2. Create a read token at https://huggingface.co/settings/tokens
  3. 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

ToolDescription
start_transcribeStart a background job — returns job_id immediately
get_transcribePoll a job for status and result
transcribeStart + wait up to N seconds inline (use for short files)
warm_modelPre-load model to avoid cold-start latency (~5-15s)
statusDaemon health, active jobs, config, and the diarization stack/ABI block (cheap, no model load)
diagnosticsActively load the pyannote pipeline and report whether diarization is healthy — run before a long transcription

Key parameters for start_transcribe

ParameterTypeDescription
pathstringAbsolute path to local audio file (m4a, mp3, wav, mp4, opus…)
languagestring | nullBCP-47 code e.g. "ru", "de", "en". Omit to auto-detect. Always set if known.
taskstring"transcribe" (default) or "translate" (→ English)
diarizebooltrue to identify speakers. Requires HF_TOKEN.
num_speakersint | nullKnown speaker count — improves diarization accuracy

Result fields (when status == "done")

FieldDescription
textPlain transcript, no speaker labels
transcript_with_speakersSpeaker-labeled blocks (present when diarize=true)
speakersList of speaker IDs e.g. ["SPEAKER_00", "SPEAKER_01"]
diarization_statusok / degraded / failed / empty — present whenever diarize=true, even on a successful transcript, so a silent fallback to plain text is never invisible
warningHuman-readable note when diarization failed or degraded (e.g. collapsed to one speaker)
languageDetected/used language code
audio_duration_sTotal audio duration in seconds

Typical completion times

Audio lengthWarm modelCold 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:

  • diagnostics actively loads the pipeline and returns {"ok": true|false, "detail": …} plus the live version matrix. Run it before a long transcription.
  • status carries a cheap diarization block (version matrix + ABI match, no model load).
  • A failed/degraded diarization now sets diarization_status + warning on the job result even when the transcript itself succeeded.
  • _load_diarize_pipeline pre-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 as diarization_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.

Ver o original no GitHub

Bom para

Relacionados