Whispernotes

Name: Whispernotes
Author: mazzzystar

@mazzzystarMCP server · External

Search, read, and create speech-to-text transcripts on-device with the Whisper Notes Mac app.

Transcriptionv0.2.0MIT

Freeno charge per call

How to install

Runs on your machine from its package; the steps are below.

What it does

Reads
Writes
High impact

At most: creates or changes data: records, files, settings.

What it costs

Free

Odel charges nothing per call. The publisher may charge for its own service.

Runs locally

This server runs on your machine over stdio, but its source registry didn't list a distribution package. Check the source repository for setup instructions.

README4 min readView on GitHub

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

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

Connect Claude or any MCP client

Claude Code — one line:

bash

claude mcp add whispernotes -- whispernotes mcp

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

json

{
  "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:

bash

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

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.

Similar modules

Browse Transcription