Skip to main content
Glama

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

CI CodeQL PyPI version License: MIT


Claude Desktop transcribing an audio file


Requirements

  • macOS (MacWhisper is macOS-only)

  • MacWhisper — installed and licensed

  • MacWhisper CLI enabled: open MacWhisper → Settings → Advanced → Command-Line Tool → Install. This places mw at /usr/local/bin/mw.

  • Python 3.13.x via pyenv

  • Claude Desktop

Installing MacWhisper via Homebrew:

brew install --cask macwhisper

After 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

brew tap docdyhr/tap
brew install docdyhr/tap/macwhisper-mcp-server

This 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-server

Or 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 version

Configure 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_audio(path, model?, language?, persist?, engine?)

Transcribe an audio file and return the transcript as plain text. language is an ISO 639-1 code (e.g. da) or auto; overrides any per-directory default. persist=true saves to MacWhisper history (MacWhisper engine only). engine is "macwhisper" (default) or "whisper-cpp" — see Alternative engine below.

list_models()

List transcription models installed in MacWhisper, plus whisper-cpp models if MACWHISPER_WHISPERCPP_MODEL_DIR is configured; active MacWhisper model is marked

cancel_transcription()

Cancel the currently running transcription

list_allowed_paths()

Return the directories the server is allowed to read from

start_watch(folder)

Watch a folder and auto-transcribe new audio files into ../done/

stop_watch()

Stop the active folder watcher

get_watch_results()

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

MACWHISPER_ALLOWED_PATHS

~/Desktop

Colon-separated list of directories the server may read from

MACWHISPER_CLI

auto-detected

Path to the mw binary. Defaults to /Applications/MacWhisper.app/Contents/MacOS/mw if that file exists, otherwise mw on PATH

MACWHISPER_LOG_PATH

~/Library/Logs/macwhisper-mcp.log

Log file path (never stdout — that's reserved for MCP)

MACWHISPER_LANGUAGE_DEFAULTS

none

Colon-separated dir=lang pairs (ISO 639-1, or auto) — files in a matching directory get --language automatically. Most specific directory wins; an explicit language argument always overrides.

MACWHISPER_WHISPERCPP_BINARY

whisper-cli on PATH

Path to the whisper-cli binary, if not on PATH. Only used when engine="whisper-cpp".

MACWHISPER_WHISPERCPP_MODEL_DIR

none

Directory containing your GGML .bin model files. Required to use engine="whisper-cpp" at all — see below.

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-cpp

Homebrew 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, .flac only — not .m4a/.mp4/.mov/.aiff. This is whisper.cpp's own native format support; convert other formats first (e.g. with ffmpeg) or use the default MacWhisper engine, which handles all supported formats.

  • persist=true is not supported — whisper.cpp has no history mechanism.

  • Default language is English (en) if neither language nor 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.m4a

Logs

tail -f ~/Library/Logs/macwhisper-mcp.log

Security

  • All file paths are resolved (symlinks followed) and checked against the MACWHISPER_ALLOWED_PATHS allow-list before anything reaches the CLI.

  • subprocess.run is always called with an argv list — never shell=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 tools
cancel_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

    A4/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Local-first meeting capture and transcription for Claude Code. Records audio from meeting apps, transcribes locally with whisper.cpp, and produces structured notes via Claude.
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Voice 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
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      6
      426 npm
      MIT