# macwhisper-mcp-server [Health: Active]

**Category:** 🎙️ Speech-to-Text  
**Repository:** https://github.com/docdyhr/macwhisper-mcp-server  
**GitHub Stars:** 3  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/macwhisper-mcp-server

## Description
MacWhisper transcription for Claude Desktop. Fully local, no cloud, audio stays on your Mac.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "macwhisper-mcp-server": {
    "command": "uvx",
    "args": ["macwhisper-mcp-server"],
    "env": {
      "MACWHISPER_ALLOWED_PATHS": "",
      "MACWHISPER_CLI": "",
      "MACWHISPER_LOG_PATH": "",
      "MACWHISPER_LANGUAGE_DEFAULTS": "",
      "MACWHISPER_WHISPERCPP_BINARY": "",
      "MACWHISPER_WHISPERCPP_MODEL_DIR": ""
    }
  }
}
```

**Requires environment variables:** `MACWHISPER_ALLOWED_PATHS`, `MACWHISPER_CLI`, `MACWHISPER_LOG_PATH`, `MACWHISPER_LANGUAGE_DEFAULTS`, `MACWHISPER_WHISPERCPP_BINARY`, `MACWHISPER_WHISPERCPP_MODEL_DIR` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What macwhisper-mcp-server does

The macwhisper-mcp-server MCP server lets Claude Desktop request local audio transcription through MacWhisper. Audio remains on the Mac: the server invokes the MacWhisper CLI, receives the transcript, and returns plain text to Claude for follow-up work such as summarization or action-item extraction.

The server supports `.m4a`, `.mp3`, `.mp4`, `.mov`, `.wav`, `.aiff`, and `.flac` files when using the MacWhisper engine. Files must already exist on the Mac; files uploaded directly into a Claude chat are stored in Claude's container and cannot be read by the local CLI.

## How it works

The normal flow is:

1. Save an audio recording in an allowed local directory.
2. Ask Claude Desktop to transcribe the file.
3. The MCP server checks the resolved path against its allow-list.
4. MacWhisper performs the transcription locally through its `mw` command-line tool.
5. Claude receives the transcript and can process it further.

The server uses standard MCP communication through its configured command. File paths are resolved, including symlinks, before the allow-list check. Commands are passed as argument arrays rather than through a shell.

An alternative `whisper-cpp` engine can use a locally installed `whisper-cli` binary and a GGML model. This path does not require MacWhisper or a MacWhisper license, but it supports only WAV, MP3, and FLAC input in the documented version.

## Setup and configuration

macOS, a licensed MacWhisper installation, its enabled command-line tool, Python 3.13.x, and Claude Desktop are listed as requirements. Enable the CLI from MacWhisper's Advanced settings, then verify it with `mw version`.

Install the server with Homebrew or pip. The Homebrew package installs the `macwhisper-mcp` executable. Add that executable to Claude Desktop's MCP configuration and restart the application.

`MACWHISPER_ALLOWED_PATHS` controls which colon-separated directories can be read; it defaults to `~/Desktop`. Other supported settings select the MacWhisper binary, log path, per-directory language defaults, whisper.cpp binary, and whisper.cpp model directory. Language defaults use ISO 639-1 codes or `auto`, and an explicit tool argument takes precedence.

## Tools and capabilities

The macwhisper-mcp-server MCP server exposes these tools:

- `transcribe_audio`: transcribes a file with optional model, language, persistence, and engine settings.
- `list_models`: lists installed MacWhisper models and configured whisper.cpp models.
- `cancel_transcription`: stops the active transcription.
- `list_allowed_paths`: reports readable directories.
- `start_watch`: watches a folder and places automatic transcription output in a neighboring `done` directory.
- `stop_watch`: stops the active watcher.
- `get_watch_results`: returns completed watcher results and clears the queue.

With the MacWhisper engine, `persist=true` can save the result to MacWhisper history. The whisper.cpp engine does not provide history persistence and uses English when no language or directory default is supplied.

## Limitations and notes

The primary integration is local macOS software, so it is not intended for environments without macOS and MacWhisper. The default configuration allows only the Desktop unless additional directories are added. Audio must be saved in those directories before Claude can access it.

The whisper.cpp option requires a separately installed binary and a manually downloaded GGML model; the server does not download models over the network. Its documented input restrictions exclude M4A, MP4, MOV, and AIFF, and its model argument uses a filename rather than a MacWhisper model identifier.

The project documents no network calls. Logs are written to a file rather than standard output, which remains reserved for MCP communication.

_Full upstream README: https://allmcps.com/mcp/macwhisper-mcp-server/readme_