macwhisper-mcp-server
Use this local MCP server to transcribe and manage Mac audio files from Claude Desktop.
Transcribe local audio files from allow-listed folders (m4a, mp3, mp4, mov, wav, aiff, flac; whisper-cpp supports wav, mp3, flac).
Choose the MacWhisper or whisper.cpp engine and override the model.
Set or auto-apply transcription language, and optionally save MacWhisper history.
List available MacWhisper and whisper-cpp models.
Cancel a running transcription.
List directories the server is allowed to read from.
Watch a folder for new audio files, auto-transcribe them, retrieve/clear results, and stop watching.
Keep transcription local with no network calls; uploaded Claude chat files are not accessible.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@macwhisper-mcp-server Transcribe ~/Desktop/meeting.m4a and summarize key points"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
macwhisper-mcp-server
Local MCP server that connects MacWhisper to Claude Desktop.
What it does: Drop an audio file on your Desktop, then ask Claude to transcribe it, summarise it, or pull out action items — in one step. MacWhisper does the transcription on your Mac; Claude does the thinking. Nothing leaves your machine. No cloud APIs. No data ever leaves your Mac.
Audio file → MacWhisper CLI → MCP server → Claude Desktop

Requirements
macOS (MacWhisper is macOS-only)
MacWhisper — installed and licensed
MacWhisper CLI enabled: open MacWhisper → Settings → Advanced → Command-Line Tool → Install. This places
mwat/usr/local/bin/mw.Python 3.13.x via pyenv
Installing MacWhisper via Homebrew:
brew install --cask macwhisperAfter installation, enable the CLI in MacWhisper Settings as above. When you later run brew upgrade --cask macwhisper, the CLI symlink updates automatically — no re-install needed.
Related MCP server: ClassNotes MCP
Install
Option A — Homebrew (recommended)
brew tap docdyhr/tap
brew install docdyhr/tap/macwhisper-mcp-serverThis installs the macwhisper-mcp binary into your Homebrew prefix. Upgrade later with brew upgrade docdyhr/tap/macwhisper-mcp-server.
Option B — pip / source
pip install macwhisper-mcp-serverOr from source:
git clone https://github.com/docdyhr/macwhisper-mcp-server.git
cd macwhisper-mcp-server
pyenv install 3.13.13 # skip if already installed
pyenv local 3.13.13
python -m venv .venv
source .venv/bin/activate
pip install -e .Verify the MacWhisper CLI is reachable:
mw versionConfigure Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json and add:
{
"mcpServers": {
"macwhisper": {
"command": "macwhisper-mcp",
"args": [],
"env": {
"MACWHISPER_ALLOWED_PATHS": "~/Desktop:~/Downloads",
"FASTMCP_CHECK_FOR_UPDATES": "off"
}
}
}
}Restart Claude Desktop.
FASTMCP_CHECK_FOR_UPDATES=off stops FastMCP from asking PyPI for a newer FastMCP at startup. Releases after 1.2.1 turn it off in code. Keep the line for 1.2.1 and earlier.
Note: Audio files must be saved to your Mac's filesystem (Desktop, Downloads, or another allow-listed folder) before asking Claude to transcribe them. Files uploaded directly to the Claude chat window live in Claude's container and are not accessible to the local MacWhisper CLI.
Verify it works
In Claude Desktop, ask:
Transcribe ~/Desktop/memo.m4a
You should see a transcribe_audio tool call appear, followed by the transcript.
Available tools
Tool | Description |
| Transcribe an audio file and return the transcript as plain text. |
| List transcription models installed in MacWhisper, plus whisper-cpp models if |
| Cancel the currently running transcription |
| Return the directories the server is allowed to read from |
| Watch a folder and auto-transcribe new audio files into |
| Stop the active folder watcher |
| Return completed watch-folder transcriptions and clear the queue |
Supported audio formats: .m4a .mp3 .mp4 .mov .wav .aiff .flac
Configuration
All configuration is via environment variables. Pass them through the env dict in claude_desktop_config.json (for Claude Desktop) or set them in .env for local development.
Env var | Default | Description |
|
| Colon-separated list of directories the server may read from |
| auto-detected | Path to the |
|
| Log file path (never stdout — that's reserved for MCP) |
| none | Colon-separated |
|
| Path to the |
| none | Directory containing your GGML |
Local development: copy .env.example to .env and adjust. With direnv, .envrc exports .env automatically. Without direnv: source .env.
Per-directory language defaults
If you regularly transcribe recordings in a specific language, map a subfolder to
it instead of passing language on every call:
"MACWHISPER_LANGUAGE_DEFAULTS": "~/Desktop/DK=da:~/Desktop/DE=de"Drop a file in ~/Desktop/DK/ and transcribe_audio passes --language da
automatically. An explicit language argument on the tool call always wins over
the directory default.
Alternative engine: whisper.cpp
transcribe_audio(..., engine="whisper-cpp") transcribes using a standalone
whisper.cpp binary instead of
MacWhisper — useful if you don't have a MacWhisper license, or want a fully
open-source local path. It does not touch MacWhisper in any way.
Setup:
brew install whisper-cppHomebrew installs the whisper-cli binary only — no models. Download a GGML
model yourself (this server never downloads anything over the network) from
huggingface.co/ggerganov/whisper.cpp,
e.g. ggml-base.en.bin, into a directory of your choice, then point the server at it:
"MACWHISPER_WHISPERCPP_MODEL_DIR": "~/whisper-models"Then call the tool with the model's filename (not a MacWhisper engine:model-id
string):
Transcribe ~/Desktop/memo.wav using the whisper-cpp engine with model ggml-base.en.bin
Limitations (v1):
Input formats:
.wav,.mp3,.flaconly — not.m4a/.mp4/.mov/.aiff. This is whisper.cpp's own native format support; convert other formats first (e.g. withffmpeg) or use the default MacWhisper engine, which handles all supported formats.persist=trueis not supported — whisper.cpp has no history mechanism.Default language is English (
en) if neitherlanguagenor a directory default is set — unlike MacWhisper, which defers to the app's own language selection.
Development
source .venv/bin/activate
pip install -e ".[dev]"
# Tests
pytest -q
# Lint + format
ruff check .
ruff format .
# Pre-commit hooks (one-time setup)
pip install pre-commit
pre-commit install
# Smoke-test against a real audio file (server must not be running in Claude Desktop)
python scripts/smoke_test.py ~/Downloads/Test.m4aLogs
tail -f ~/Library/Logs/macwhisper-mcp.logSecurity
All file paths are resolved (symlinks followed) and checked against the
MACWHISPER_ALLOWED_PATHSallow-list before anything reaches the CLI.subprocess.runis always called with an argv list — nevershell=True.No network calls. Ever.
See PRD §7 for the full threat model.
Known limitations
Uploaded files: Files dragged into the Claude chat window live in Claude's container and are not accessible to the local MacWhisper CLI. Save the file to your Desktop or Downloads folder (or another allow-listed directory), then ask Claude to transcribe it from there.
Danish letter names: Whisper may phonetically approximate letter names (e.g. "Æ, Ø, Å" → "E, Y, U") when they are spoken in isolation. Letters inside words transcribe correctly. This is a Whisper engine limitation, not a bug in this wrapper. See PRD §12.
Cold-start latency: First transcription after MacWhisper launches takes ~13s (model load). Subsequent calls are ~2s.
License
MIT — see LICENSE.
Available Tools
7 toolscancel_transcriptionCancel TranscriptionA
Cancel the currently running transcription, if any.
Inputs: no named parameters. Returns: result
get_watch_resultsGet Watch ResultsA
Return completed watch-folder transcriptions and clear the queue.
Each entry contains: file, transcript, destination, error.
Inputs: no named parameters. Returns: result
list_allowed_pathsList Allowed PathsA
Return the directories this server is allowed to read audio from.
Inputs: no named parameters. Returns: result
list_modelsList ModelsA
Return the transcription models available across all engines.
MacWhisper entries are formatted as engine:model-id — Display Name [active]
where [active] marks the model currently selected in MacWhisper; pass the
engine:model-id string as model with the default engine="macwhisper".
whisper-cpp entries (if MACWHISPER_WHISPERCPP_MODEL_DIR is configured) are
formatted as filename [whisper-cpp]; pass the filename as model with
engine="whisper-cpp". Requires the MacWhisper CLI to be reachable even if
you only intend to use the whisper-cpp engine.
Inputs: no named parameters. Returns: result
start_watchStart WatchA
Start watching a folder for new audio files to auto-transcribe.
New audio files dropped into folder are transcribed automatically
and moved to a "done" directory. By default this is <folder>/../done;
override it with the MACWHISPER_WATCH_DONE_DIR env var. Both the
incoming folder and the done directory must be inside the configured
allow-list, otherwise the call is rejected. Call get_watch_results()
to retrieve completed transcriptions.
Inputs: folder (required). Returns: result
stop_watchStop WatchB
Stop the active folder watcher.
Inputs: no named parameters. Returns: result
transcribe_audioTranscribe AudioA
Transcribe a local audio file and return the transcript.
IMPORTANT: path must be a file on the user's Mac filesystem inside the
configured allow-list (typically ~/Desktop or ~/Downloads). Files uploaded
to the Claude chat window are NOT accessible — ask the user to save the file
to their Desktop or Downloads folder first.
If this tool returns an access-denied error, do NOT attempt to transcribe the file by any other means (e.g. downloading a model, calling an external API, or using in-process speech recognition). Simply tell the user to save the file locally and retry with this tool.
Inputs: path (required), model, engine, persist, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct action: single-file transcription, cancellation, model listing, path listing, and the watch lifecycle (start/stop/results). The watch tools and direct transcription tools have clearly separated purposes with no overlap. An agent can easily tell them apart.
All seven tools follow a consistent snake_case verb_noun pattern (transcribe_audio, cancel_transcription, list_models, list_allowed_paths, start_watch, stop_watch, get_watch_results). Verb choices are precise and predictable.
Seven tools is well-scoped for a focused transcription server. Every tool earns its place: core transcription, lifecycle control, discovery helpers, and the watch-folder feature set.
Core lifecycle is covered (transcribe, cancel, watch start/stop/results, model and path discovery). Minor gap: there is no status/progress query for an in-flight transcription beyond cancel, but agents can reasonably work around this.
Maintenance
Related MCP Connectors
Ask Claude about your meetings: summaries, action items and transcripts from Roomtone
Read, summarize and act on the voice memos you record with Whisper Memos.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Connect Claude to Fathom meeting recordings, transcripts, and summaries
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceLocal-first meeting capture and transcription for Claude Code. Records audio from meeting apps, transcribes locally with whisper.cpp, and produces structured notes via Claude.1Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables Claude Desktop to manage an Obsidian vault and automatically convert class recordings into structured study notes using local AI tools.-
- AlicenseNot gradedqualityDmaintenanceVoice interface for Claude Code enabling hands-free, conversational interaction entirely on-device for Apple Silicon Macs. It provides push-to-talk transcription and automatic spoken responses via local AI models.MIT
- AlicenseAqualityBmaintenanceEnables spoken conversations with Claude on a Mac: Claude speaks through speakers, listens to the user's natural replies, and transcribes them locally. No audio leaves the computer, and it includes tools for voice setup and a hands-free voice mode.6426 npmMIT