Whisper Notes

Search, read, and create speech-to-text transcripts on-device with the Whisper Notes Mac app — 100% offline, no open ports.

View on whispernotes.app

Documentation

Set up

Download Whisper Notes for Mac 1.5.5 or later — DMG version (not Mac App Store).
Open the app → Settings → Integrations → toggle on Local CLI & MCP.
Click Install CLI in the same section — this puts whispernotes (and the wn shorthand, when that name is free) in your terminal.

The examples below use the short alias wn. If wn is already taken on your Mac (e.g. by WordNet), the full command whispernotes works identically.

Use the CLI

$ wn status
WhisperNotes 1.5.5 (340) · SenseVoice Small · ready · 3081 notes

$ wn list --limit 3
9f3c21a8  2026-08-01 09:14  0:42   meeting   Weekly sync — pricing review
b2d84e07  2026-07-31 18:03  12:26  recorded  Idea dump on the walk home
5a1f9c33  2026-07-30 10:52  47:10  imported  interview-with-anna.m4a

$ wn transcribe ~/Desktop/standup.m4a
Morning standup. Sarah shipped the pricing page, Marco is blocked on the…
✓ done in 6.5s (46x realtime) — saved to WhisperNotes history

$ wn export --format md --audio --output-dir ~/Transcripts
✓ exported 312/312 transcript(s), 312 audio file(s) → /Users/you/Transcripts

Transcripts print to stdout, progress and errors go to stderr — safe to pipe or redirect anything. Add --json for machine-readable output. Everything else is in the command reference.

Connect Claude or any AI agent (MCP)

The MCP server is built into the same binary — nothing else to install.

Claude Code — one line:

claude mcp add whispernotes -- whispernotes mcp

Claude Desktop — add this to ~/Library/Application Support/Claude/claude_desktop_config.json, then restart Claude Desktop:

{
  "mcpServers": {
    "whispernotes": {
      "command": "/usr/local/bin/whispernotes",
      "args": ["mcp"]
    }
  }
}

Then just ask:

"Read my last five transcripts and tell me what I should follow up on."
"Find the meeting where we discussed the invoice, and draft a reply email."
"Transcribe ~/Desktop/podcast.mp3 and pull out every action item."

Notes:

Any local MCP client works the same way — command whispernotes, args ["mcp"] (Cursor, etc.).
If the command isn't found, use the full path from which whispernotes — GUI apps don't read your shell's PATH.
The claude.ai website can't reach local MCP servers — use Claude Desktop instead.

What you can do with it

# Summarize your latest recording with a local LLM
wn show latest | ollama run llama3 "Summarize the key points:"

# Transcribe an interview straight into the clipboard
wn transcribe interview.mp3 | pbcopy

# Who said what — speaker-labeled transcript of your last meeting
wn show latest --speakers

# Find that one conversation
wn search "quarterly review"

# Review only your meeting recordings
wn list --source meeting --limit 10

# Switch the transcription model, then see which languages it takes
wn models select sensevoice
wn language list

Command reference

Command	Options	What it does
status	—	App version, active model, readiness, note count
list	--limit N · --source T · --json	Recent transcripts, newest first
search	--limit N · --json	Full-text search across your history, with snippets
show [id or latest]	--timestamps · --speakers · --max-chars N · --offset N · --json	Print one transcript (defaults to latest)
transcribe	--json	Transcribe an audio or video file, save it to history
export	--format txt or md · --output-dir DIR · --source T · --limit N · --audio · --speakers	Batch-export transcripts as files, optionally copying the audio alongside
models	list · select	List or switch models: parakeet, sensevoice, whisper-small, whisper-large-v3-turbo
language	list · select	List or switch transcription language — choices follow the active model
mcp	—	Run the MCP server on stdio (for AI clients, not humans)
version · help	—	CLI version · usage

Worth knowing:

wn is a convenience alias for whispernotes — identical commands. Scripts and AI agents should call whispernotes, which always exists; the alias is only created when the name is free.
Self-discovery for agents: whispernotes help prints the full usage; a misused command replies with its exact usage line on stderr. --json always emits a single JSON object or array on stdout.
show takes the full id or just its first 4+ characters as shown by list — or latest, which is the default.
--speakers (on show and export) uses the speaker detection you've already run in the app; export quietly falls back to plain text for notes without it.
export writes date-titled files (2026-08-01-1956 Standup.md), never overwrites, and defaults to ./whispernotes-export; Markdown files carry date, duration, source, and id up top.
--source filters by origin: recorded, imported, meeting, or fn (Fn-key voice typing).
transcribe uses the model and language currently selected in the app, and the result is also saved into your history.
If Whisper Notes isn't running, the CLI launches it in the background and waits up to ~15 seconds.

MCP tools

Tool	Parameters	Returns
list_transcripts	limit (default 20) · source	Recent transcripts with ids, dates, titles
search_transcripts	query (required) · limit	Full-text matches with snippets
get_transcript	id (required) · timestamps · speakers · max_chars · offset	One transcript's text
get_latest_transcript	timestamps · speakers	Your most recent transcript
transcribe_file	path (required)	Transcribes an audio or video file, saves it to history
list_models	—	Installed models and which one is active

Long recordings are paged: when a transcript exceeds max_chars, the response ends with an explicit truncation marker telling the agent which offset to continue from — hour-long meetings never overflow a context window.

Privacy & security

Transport is a Unix domain socket at ~/Library/Application Support/WhisperNotes/api.sock with 0600 permissions — no TCP port, no network interface, unreachable from any other machine.
Off by default: nothing is served until you enable the toggle in Settings.
MCP clients like Claude ask for your approval before each tool call.
Transcription runs on-device with the same engines as the app; results are stored only in your local history.

Troubleshooting

command not found: whispernotes — install the command-line tool from Settings → Integrations in the app, then open a new terminal window (both whispernotes and wn should work).
"the local API is disabled" — enable Settings → Integrations → Local CLI & MCP in Whisper Notes. It applies instantly, no restart needed.
"The running WhisperNotes does not include Local API support" — your app predates the Local API. Update to 1.5.5 or later via the in-app updater or the latest DMG.
First transcription is slow to start — the model may still be loading; the server waits for it to become ready. whispernotes status shows loading model… until the engine is warm.