Whisper Notes CLI & MCP Server

Set up

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

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

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

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.

See also

• Download Whisper Notes for Mac (DMG)
• Changelog
• Privacy policy
• Raw markdown of this page for agents: whispernotes.app/cli-mcp.md
• Questions or ideas: support@whispernotes.app