MCP Setup

The @hyperwhisper/mcp package is a Model Context Protocol bridge for the local API. You configure this bridge one time. Then any MCP-capable agent can call HyperWhisper as a tool: Cursor, Claude Desktop, Claude Code, Zed, or your own code.

Prerequisites

Install HyperWhisper for macOS or Windows, then open it one time. Both apps write the discovery file that the bridge reads.
Turn on the local API server: Settings → API Server on macOS, or Settings → Local API on Windows. This setting writes the discovery file that the bridge reads.
Put Node.js 18 or newer on your PATH. Run node --version to see the version number. If the command fails, install Node.js from nodejs.org. Node.js includes the npx command.

You do not need a global installation of the bridge. The npx -y @hyperwhisper/mcp command downloads the bridge and runs it on demand. Each MCP client in this page uses that command directly.

Linux is not supported yet. The bridge selects the discovery path from the platform. It uses the Windows path on Windows and the macOS path everywhere else, so on Linux it looks for ~/Library/Application Support/HyperWhisper/local-api.json. That file never exists on Linux, and the bridge reports HYPERWHISPER_NOT_RUNNING.The Linux app itself writes a valid discovery file, and its Local API settings show this same MCP block. Until the bridge adds the Linux path, call the endpoints directly. See the cURL snippet in Local API Server.

Tools the bridge supplies

Tool	What the agent gets
`health`	Makes sure that HyperWhisper runs. No authentication is necessary.
`list_models`	Catalog of voice and post-processing models.
`list_modes`	Saved transcription Modes.
`transcribe`	Transcribes an audio file at an absolute path. The file must be in your recordings folder (see the note in this page). The tool can write the transcript directly to a file with `output_path` and return only a confirmation. This keeps long transcripts out of the context of the agent. The tool also accepts `mode_id`, an `engine`/`model` override, `language`, `timestamp_granularities`, and `post_process_preset`/`post_process_prompt`. The two post-process options clean the result in the same call. If you use one of them without `output_path`, the call fails with `INVALID_ARGUMENTS`. You also cannot combine `timestamp_granularities` with `output_path`, because the app does not write caption files to disk yet. To get timestamps in the response, omit `output_path`.
`post_process`	Rewrites text with a preset (`hyper`, `note`, `email`, `commit`, `prompt`) or with a free-form `prompt` field. You can use a preset or a prompt field, but not both. Optional `provider`/`model` overrides replace your default post-processing settings for one call. Only `hyper` and `note` map to a real backend preset at this time. `email`, `commit`, and the `prompt` preset value all give Hyper-style output instead, with no message — use the separate `prompt` field, not the `prompt` preset value, to send a free-form instruction.
`search_recordings`	Searches past transcripts for a substring. The tool accepts an optional `q` substring and the `since`, `until`, and `limit` filters.
`get_recording`	Gets one transcript row by ID.

Cursor

Open ~/.cursor/mcp.json. Add the hyperwhisper entry:

{
  "mcpServers": {
    "hyperwhisper": {
      "command": "npx",
      "args": ["-y", "@hyperwhisper/mcp"]
    }
  }
}

Restart Cursor. The server appears under Settings → MCP.

Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json. Add the same entry:

{
  "mcpServers": {
    "hyperwhisper": {
      "command": "npx",
      "args": ["-y", "@hyperwhisper/mcp"]
    }
  }
}

Quit Claude Desktop, then open it again. The hammer icon in the composer lists hyperwhisper.

Claude Code

Run the CLI helper:

claude mcp add hyperwhisper -- npx -y @hyperwhisper/mcp

In a new session, /mcp lists hyperwhisper with its tools.

Make sure that the bridge works

Open a new agent session. Then give the agent this instruction:

Use hyperwhisper to transcribe a file in my recordings folder

The agent calls the transcribe tool and returns the text inline. If you do not have an audio file, use this instruction instead: Ask hyperwhisper to run a health check. The agent then calls health and reports the version of the app.

transcribe reads files only in your HyperWhisper recordings folder. The tool rejects a different path such as /Users/me/Desktop/test.wav (FILE_ACCESS_DENIED on macOS, FILE_NOT_ALLOWED on Windows). The agent can use a file that HyperWhisper saved (see History), or an audio file that you copied into that folder.

Write transcripts to a file

For a long recording, ask the agent to save the transcript to a file instead:

Transcribe ~/notes/memo.wav and save the cleaned-up text to ~/notes/memo.md

The agent sets output_path. The agent can also set post_process_preset or post_process_prompt to clean the text first. The bridge then writes the file and returns a short confirmation, not the full transcript. The confirmation payload contains ok, the resolved if_exists mode, and written_to (the resolved absolute path of the file). It also contains the bytes of the file, the engine/model/language in use, latency_ms, the post_processed result, a character count, a 200-character preview, and an optional warning field. The full transcript never enters the context of the agent. If the file exists, the tool fails by default. The agent can pass if_exists: "overwrite" or if_exists: "append". The append mode is useful for a notes file that grows.

Troubleshooting

HYPERWHISPER_NOT_RUNNING — the discovery file is missing. Open HyperWhisper. Then turn on the local API server (Settings → API Server on macOS, Settings → Local API on Windows). Run the agent prompt again. INVALID_REQUEST — a general bad-request code. Usually the bearer token in the discovery file does not match the token that the server expects, and you see an HTTP 401. This mismatch occurs after you use Regenerate token in Settings. The bridge reads the discovery file again on each request, and the next agent call is successful. INVALID_ARGUMENTS — the bridge returns this code for a bad call, before the request reaches HyperWhisper. Examples: a missing required field, post_process_preset/post_process_prompt on transcribe without output_path, or timestamp_granularities with output_path. Connection refused — a force-quit stopped the app before its cleanup, and the port in the discovery file is out of date. Turn the Local API switch off, then on again. This writes a new local-api.json file. npx hangs on first run — npx -y downloads the package on the first run. Later runs start immediately. If your network blocks the npm registry, install the package one time with npm i -g @hyperwhisper/mcp. Then replace npx -y @hyperwhisper/mcp with hyperwhisper-mcp in the configuration examples in this page. Other app-level error codes — the app returns a fixed set of error codes for tool calls: MODEL_NOT_INSTALLED, MODEL_NOT_FOUND, ENGINE_UNAVAILABLE, MISSING_API_KEY, FILE_NOT_FOUND, FILE_ACCESS_DENIED, FILE_NOT_ALLOWED, AUDIO_DECODE_FAILED, TRANSCRIPTION_FAILED, MODE_NOT_FOUND, MODE_NAME_TAKEN, INVALID_REQUEST, RATE_LIMITED, and TIMEOUT. Each code comes with a message in clear language that the agent can give to you.

Getting Started

Plans & Billing

Transcription & Models

The Interface

Features

Settings

Privacy & Security

Developer & API

Troubleshooting

Windows

Prerequisites

Tools the bridge supplies

Cursor

Claude Desktop

Claude Code

Make sure that the bridge works

Write transcripts to a file

Troubleshooting

​Prerequisites

​Tools the bridge supplies

​Cursor

​Claude Desktop

​Claude Code

​Make sure that the bridge works

​Write transcripts to a file

​Troubleshooting

Prerequisites

Tools the bridge supplies

Cursor

Claude Desktop

Claude Code

Make sure that the bridge works

Write transcripts to a file

Troubleshooting