whispernotes

Whisper Notes MCP Server & CLI

MCP server and command-line access to Whisper Notes — on-device speech-to-text for Mac and iPhone. Claude and any MCP client can search your transcript history, read transcripts (plain, timestamped, or speaker-labeled), and transcribe audio or video files.

100% on-device. The server speaks over a local Unix socket (0600 permissions) — no open ports, no network interface, no cloud. Your audio and transcripts never leave your Mac.

The MCP server is built into the Whisper Notes Mac app — there is nothing to npx or pip install. This repository is its documentation and registry home. Canonical docs live at whispernotes.app/cli-mcp (agent-readable markdown: whispernotes.app/cli-mcp.md).

Set up

1. Download Whisper Notes for Mac 1.5.5 or later — Direct Download (DMG) version (the Mac App Store build does not include the Local API). macOS 14+, Apple Silicon.
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.

Connect Claude or any MCP client

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"]
    }
  }
}

Use the full path from which whispernotes — GUI apps don't read your shell's PATH. Any other local MCP client (Cursor, etc.) works the same way: command whispernotes, args ["mcp"]. Transport is stdio; there is no HTTP endpoint.

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."

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.

CLI

The same binary is a full command-line tool:

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

$ whispernotes 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

$ whispernotes show latest | ollama run llama3 "Summarize the key points:"

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

Command	Options	What it does
status	—	App version, active model, readiness, note count
list	--limit N · --source T · --json	Recent transcripts, newest first
search <query>	--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 <file>	--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, optionally copying the audio alongside
models	list · select <id>	List or switch models: parakeet, sensevoice, whisper-small, whisper-large-v3-turbo
language	list · select <code>	List or switch transcription language — choices follow the active model
mcp	—	Run the MCP server on stdio
version · help	—	CLI version · usage

Results go to stdout, progress and errors to stderr — safe to pipe or redirect. --json always emits a single JSON object or array. whispernotes help prints the full usage; a misused command replies with its exact usage line. wn is a convenience alias — scripts and agents should call whispernotes, which always exists.

Privacy & security

• Transport is a Unix domain socket at ~/Library/Application Support/WhisperNotes/api.sock with 0600 permissions — only your macOS user account can connect. 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 (Parakeet V3, Whisper, SenseVoice on the Neural Engine / MLX); results are stored only in your local history.

Links

• Docs: whispernotes.app/cli-mcp · raw markdown for agents: /cli-mcp.md
• Download: Whisper Notes for Mac (DMG)
• iPhone & Mac App Store: App Store
• Website: whispernotes.app · Changelog · Privacy
• Support: [email protected]

License

The contents of this repository (documentation and metadata) are MIT-licensed. Whisper Notes itself — the application, including the embedded MCP server and CLI — is commercial software; see whispernotes.app for terms.