macwhisper-mcp-server

Overview Schema Source Related Servers Discussions Admin

Transcribe Audio

transcribe_audio

Convert local Mac audio files to text using an allowed filesystem path. Save recordings to Desktop or Downloads first, then run to get transcripts.

Instructions

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.

Input Schema

Name	Required	Description	Default
`path`	Yes	Absolute or ``~``-prefixed path to an audio file on the local Mac filesystem inside the configured allow-list. Supported formats: m4a, mp3, mp4, mov, wav, aiff, flac (whisper-cpp engine only: wav, mp3, flac).
`model`	No	Optional model override. For the default ``engine="macwhisper"``, an engine:model-id string, e.g. "whisperkit:openai_whisper-large-v3-v20240930" — use ``list_models()`` to see what is installed. For ``engine="whisper-cpp"``, this is REQUIRED and must be the filename of a GGML model inside ``MACWHISPER_WHISPERCPP_MODEL_DIR`` (not an engine:model-id string).
`engine`	No	"macwhisper" (default) — routes through the MacWhisper CLI, or "whisper-cpp" — an independent local backend that does not use MacWhisper at all. Requires whisper-cpp installed (`brew install whisper-cpp`) and MACWHISPER_WHISPERCPP_MODEL_DIR set.	macwhisper
`persist`	No	If True, save the transcription to MacWhisper's history. Defaults to False. Not supported by the whisper-cpp engine.
`language`	No	Optional ISO 639-1 code (e.g. "da", "de") or "auto" to force the transcription language. If omitted, a per-directory default is used when the file's folder matches one configured in MACWHISPER_LANGUAGE_DEFAULTS; otherwise the engine's own default applies (MacWhisper: app selection; whisper-cpp: English).

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv1.2.0Aug 13, 2026

addedInput schema / properties / engine

Added value: +{
+  "default": "macwhisper",
+  "description": "\"macwhisper\" (default) — routes through the MacWhisper CLI, or\n\"whisper-cpp\" — an independent local backend that does not use\nMacWhisper at all. Requires whisper-cpp installed\n(`brew install whisper-cpp`) and MACWHISPER_WHISPERCPP_MODEL_DIR set.",
+  "type": "string"
+}

addedInput schema / properties / language

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional ISO 639-1 code (e.g. \"da\", \"de\") or \"auto\" to force\nthe transcription language. If omitted, a per-directory default is\nused when the file's folder matches one configured in\nMACWHISPER_LANGUAGE_DEFAULTS; otherwise the engine's own default\napplies (MacWhisper: app selection; whisper-cpp: English)."
+}

changedInput schema / properties / model / description

Previous value: -"Optional model override in MacWhisper engine:model-id format,\ne.g. \"whisperkit:openai_whisper-large-v3-v20240930\". Use\n``list_models()`` to see what is installed. Defaults to the\nmodel currently selected in MacWhisper."New value: +"Optional model override. For the default ``engine=\"macwhisper\"``,\nan engine:model-id string, e.g.\n\"whisperkit:openai_whisper-large-v3-v20240930\" — use ``list_models()``\nto see what is installed. For ``engine=\"whisper-cpp\"``, this is\nREQUIRED and must be the filename of a GGML model inside\n``MACWHISPER_WHISPERCPP_MODEL_DIR`` (not an engine:model-id string)."

changedInput schema / properties / path / description

Previous value: -"Absolute or ``~``-prefixed path to an audio file on the local Mac\nfilesystem inside the configured allow-list.\nSupported formats: m4a, mp3, mp4, mov, wav, aiff, flac."New value: +"Absolute or ``~``-prefixed path to an audio file on the local Mac\nfilesystem inside the configured allow-list.\nSupported formats: m4a, mp3, mp4, mov, wav, aiff, flac (whisper-cpp\nengine only: wav, mp3, flac)."

changedInput schema / properties / persist / description

Previous value: -"If True, save the transcription to MacWhisper's history.\nDefaults to False."New value: +"If True, save the transcription to MacWhisper's history.\nDefaults to False. Not supported by the whisper-cpp engine."

First observedv0.1.0May 28, 2026

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does well: it discloses the local-file allow-list constraint, the inaccessibility of chat uploads, and the required behavior after an access-denied error. It does not describe whether transcription is cancellable or synchronous beyond implying a direct return, but the operational warnings are substantive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action, followed by two focused paragraphs that each add necessary operational guidance. There is no filler, and the emphasis on path constraints and error handling is well placed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given five parameters, full schema coverage, and an output schema, the description is largely complete for invoking the tool correctly. It covers the critical local-path limitation and failure mode, though it could mention preparatory sibling tools such as list_allowed_paths or list_models for model discovery.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all five parameters including path, model, engine, persist, and language. The description adds practical meaning to path by emphasizing local allow-list access and ruling out uploaded files, which is useful but only covers one parameter beyond the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: transcribe a local audio file and return the transcript. It also establishes scope through the local-filesystem allow-list requirement, making it easy to distinguish from sibling tools such as start_watch or list_models.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear usage context and prerequisites: the file must be on the Mac filesystem inside the allow-list, uploaded chat files are not accessible, and access-denied errors should not be worked around. However, it does not explicitly compare this tool to siblings like start_watch or suggest list_allowed_paths as a preparatory step.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server