The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Whispernotes listing page.
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
npxorpip 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).
whispernotes (and the wn shorthand, when that name is free) in your terminal.Claude Code — one line:
Claude Desktop — add this to ~/Library/Application Support/Claude/claude_desktop_config.json, then restart Claude Desktop:
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:
| 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.
The same binary is a full command-line tool:
| 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.
~/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.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.