Whisper Notes CLI & MCP Server

Set up

1. Download Whisper Notes for Mac from our website. The CLI and MCP server are only in this Mac app, not in the Mac App Store version.
2. Open the app → Settings → Integrations → toggle on Local CLI & MCP.
3. Click Install CLI in the same section. After an admin prompt it creates two symlinks: /usr/local/bin/whispernotes, and /usr/local/bin/wn (only if that name is free). It never edits your shell config or PATH. Both links point to the copy in ~/Library/Application Support/WhisperNotes/bin, which the app refreshes at every launch — you don't need to add that folder to your PATH.

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."
• "Search my voice memos for the idea I had about the onboarding flow."
• "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.
• You may not need export for Markdown at all: the app saves every transcript as a .md file next to its audio, with YAML front matter (created, source, duration, audio, tags), in ~/Documents/WhisperNotes/ by default. Change the folder in Settings → Storage — point it at an Obsidian vault and each new recording lands there as a note.
• --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 in ~/Library/Application Support/WhisperNotes/ 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 after installing — run ls -l /usr/local/bin/whispernotes. If it's missing, the admin prompt was cancelled: click Install CLI again in Settings → Integrations. If it exists, /usr/local/bin isn't on your PATH: add export PATH="/usr/local/bin:$PATH" to ~/.zshrc and open a new terminal window.
• "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 the latest version with the in-app updater, or download the latest version from our website.
• 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
• Changelog
• Privacy policy
• Raw markdown of this page for agents: whispernotes.app/cli-mcp.md
• Questions or ideas: support@whispernotes.app