{
  "markdown": "<div align=\"right\">\n\n<a href=\"https://railway.com?referralCode=QhjuBc\">\n\n  <img width=\"160\" src=\"https://raw.githubusercontent.com/docdyhr/.github/main/assets/railway-corner-v2@2x.png\" alt=\"Deploy on Railway — $20 free credits\">\n\n</a>\n\n</div>\n\n# macwhisper-mcp-server\n<!-- mcp-name: io.github.docdyhr/macwhisper-mcp-server -->\n\nLocal MCP server that connects [MacWhisper](https://goodsnooze.gumroad.com/l/macwhisper) to [Claude Desktop](https://claude.ai/download).\n\n**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.\n\n```\nAudio file  →  MacWhisper CLI  →  MCP server  →  Claude Desktop\n```\n\n[![CI](https://github.com/docdyhr/macwhisper-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/docdyhr/macwhisper-mcp-server/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/docdyhr/macwhisper-mcp-server/actions/workflows/codeql.yml/badge.svg)](https://github.com/docdyhr/macwhisper-mcp-server/actions/workflows/codeql.yml)\n[![PyPI version](https://img.shields.io/pypi/v/macwhisper-mcp-server)](https://pypi.org/project/macwhisper-mcp-server/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n\n---\n\n![Claude Desktop transcribing an audio file](images/MacWhisper-MCP-server.png)\n\n---\n\n## Requirements\n\n- macOS (MacWhisper is macOS-only)\n- [MacWhisper](https://goodsnooze.gumroad.com/l/macwhisper) — installed and licensed\n- MacWhisper CLI enabled: open MacWhisper → Settings → Advanced → Command-Line Tool → Install. This places `mw` at `/usr/local/bin/mw`.\n- Python 3.13.x via [pyenv](https://github.com/pyenv/pyenv)\n- [Claude Desktop](https://claude.ai/download)\n\n**Installing MacWhisper via Homebrew:**\n```bash\nbrew install --cask macwhisper\n```\nAfter 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.\n\n---\n\n## Install\n\n### Option A — Homebrew (recommended)\n\n```bash\nbrew tap docdyhr/tap\nbrew install docdyhr/tap/macwhisper-mcp-server\n```\n\nThis installs the `macwhisper-mcp` binary into your Homebrew prefix. Upgrade later with `brew upgrade docdyhr/tap/macwhisper-mcp-server`.\n\n### Option B — pip / source\n\n```bash\npip install macwhisper-mcp-server\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/docdyhr/macwhisper-mcp-server.git\ncd macwhisper-mcp-server\n\npyenv install 3.13.13   # skip if already installed\npyenv local 3.13.13\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\n```\n\nVerify the MacWhisper CLI is reachable:\n\n```bash\nmw version\n```\n\n---\n\n## Configure Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` and add:\n\n```json\n{\n  \"mcpServers\": {\n    \"macwhisper\": {\n      \"command\": \"macwhisper-mcp\",\n      \"args\": [],\n      \"env\": {\n        \"MACWHISPER_ALLOWED_PATHS\": \"~/Desktop:~/Downloads\",\n        \"FASTMCP_CHECK_FOR_UPDATES\": \"off\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop.\n\n> **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.\n\n### Verify it works\n\nIn Claude Desktop, ask:\n\n> Transcribe ~/Desktop/memo.m4a\n\nYou should see a `transcribe_audio` tool call appear, followed by the transcript.\n\n---\n\n## Available tools\n\n| Tool | Description |\n|------|-------------|\n| `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](#alternative-engine-whispercpp) below. |\n| `list_models()` | List transcription models installed in MacWhisper, plus whisper-cpp models if `MACWHISPER_WHISPERCPP_MODEL_DIR` is configured; active MacWhisper model is marked |\n| `cancel_transcription()` | Cancel the currently running transcription |\n| `list_allowed_paths()` | Return the directories the server is allowed to read from |\n| `start_watch(folder)` | Watch a folder and auto-transcribe new audio files into `../done/` |\n| `stop_watch()` | Stop the active folder watcher |\n| `get_watch_results()` | Return completed watch-folder transcriptions and clear the queue |\n\nSupported audio formats: `.m4a` `.mp3` `.mp4` `.mov` `.wav` `.aiff` `.flac`\n\n---\n\n## Configuration\n\nAll 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.\n\n| Env var | Default | Description |\n|---------|---------|-------------|\n| `MACWHISPER_ALLOWED_PATHS` | `~/Desktop` | Colon-separated list of directories the server may read from |\n| `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` |\n| `MACWHISPER_LOG_PATH` | `~/Library/Logs/macwhisper-mcp.log` | Log file path (never stdout — that's reserved for MCP) |\n| `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. |\n| `MACWHISPER_WHISPERCPP_BINARY` | `whisper-cli` on `PATH` | Path to the `whisper-cli` binary, if not on `PATH`. Only used when `engine=\"whisper-cpp\"`. |\n| `MACWHISPER_WHISPERCPP_MODEL_DIR` | none | Directory containing your GGML `.bin` model files. Required to use `engine=\"whisper-cpp\"` at all — see below. |\n\n**Local development:** copy `.env.example` to `.env` and adjust. With [direnv](https://direnv.net/), `.envrc` exports `.env` automatically. Without direnv: `source .env`.\n\n### Per-directory language defaults\n\nIf you regularly transcribe recordings in a specific language, map a subfolder to\nit instead of passing `language` on every call:\n\n```json\n\"MACWHISPER_LANGUAGE_DEFAULTS\": \"~/Desktop/DK=da:~/Desktop/DE=de\"\n```\n\nDrop a file in `~/Desktop/DK/` and `transcribe_audio` passes `--language da`\nautomatically. An explicit `language` argument on the tool call always wins over\nthe directory default.\n\n### Alternative engine: whisper.cpp\n\n`transcribe_audio(..., engine=\"whisper-cpp\")` transcribes using a standalone\n[whisper.cpp](https://github.com/ggml-org/whisper.cpp) binary instead of\nMacWhisper — useful if you don't have a MacWhisper license, or want a fully\nopen-source local path. It does not touch MacWhisper in any way.\n\n**Setup:**\n\n```bash\nbrew install whisper-cpp\n```\n\nHomebrew installs the `whisper-cli` binary only — no models. Download a GGML\nmodel yourself (this server never downloads anything over the network) from\n[huggingface.co/ggerganov/whisper.cpp](https://huggingface.co/ggerganov/whisper.cpp/tree/main),\ne.g. `ggml-base.en.bin`, into a directory of your choice, then point the server at it:\n\n```json\n\"MACWHISPER_WHISPERCPP_MODEL_DIR\": \"~/whisper-models\"\n```\n\nThen call the tool with the model's filename (not a MacWhisper `engine:model-id`\nstring):\n\n> Transcribe ~/Desktop/memo.wav using the whisper-cpp engine with model ggml-base.en.bin\n\n**Limitations (v1):**\n- Input formats: `.wav`, `.mp3`, `.flac` only — not `.m4a`/`.mp4`/`.mov`/`.aiff`. This\n  is whisper.cpp's own native format support; convert other formats first (e.g. with\n  `ffmpeg`) or use the default MacWhisper engine, which handles all supported formats.\n- `persist=true` is not supported — whisper.cpp has no history mechanism.\n- Default language is English (`en`) if neither `language` nor a directory default\n  is set — unlike MacWhisper, which defers to the app's own language selection.\n\n---\n\n## Development\n\n```bash\nsource .venv/bin/activate\npip install -e \".[dev]\"\n\n# Tests\npytest -q\n\n# Lint + format\nruff check .\nruff format .\n\n# Pre-commit hooks (one-time setup)\npip install pre-commit\npre-commit install\n\n# Smoke-test against a real audio file (server must not be running in Claude Desktop)\npython scripts/smoke_test.py ~/Downloads/Test.m4a\n```\n\n### Logs\n\n```bash\ntail -f ~/Library/Logs/macwhisper-mcp.log\n```\n\n---\n\n## Security\n\n- All file paths are resolved (symlinks followed) and checked against the `MACWHISPER_ALLOWED_PATHS` allow-list before anything reaches the CLI.\n- `subprocess.run` is always called with an argv list — never `shell=True`.\n- No network calls. Ever.\n\nSee [PRD §7](./PRD.md) for the full threat model.\n\n---\n\n## Known limitations\n\n- **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.\n- **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](./PRD.md).\n- **Cold-start latency:** First transcription after MacWhisper launches takes ~13s (model load). Subsequent calls are ~2s.\n\n---\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n",
  "bytes": 9586,
  "sha": "23f56d0c04d21eaf263c8103a37209c696496a4d389229380c3f141dca19e2af",
  "repo_slug": "docdyhr/macwhisper-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_docdyhr_macwhisper_mcp_server_6a739c5c/readme"
}