Whispernotes

io.github.mazzzystarPublished by GitHub account mazzzystarv0.2.0Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyFiles & StorageKnowledge & MemoryMedia & Design

Overview

AI-generated overview

Lets an assistant search, read, and create on-device speech-to-text transcripts from the Whisper Notes Mac app.

What you can do
The server exposes tools to list recent transcripts, run full-text search over transcript history, and fetch a single transcript as plain text, with timestamps, or with speaker labels. It can also transcribe a local audio or video file and save the result to history, and list installed transcription models. Long recordings are paged so a transcript can be read in chunks.
When to use it
Useful when you keep meeting, voice-note, or interview recordings in Whisper Notes on a Mac and want an assistant to search them, summarize them, or pull action items. It suits local, privacy-conscious workflows where transcripts should stay on the machine.
Requirements
macOS 14 or later on Apple Silicon, and the Direct Download (DMG) build of Whisper Notes for Mac 1.5.5 or later; the Mac App Store build lacks the Local API. The MCP server is built into the app, so no npm or pip install is needed. You must enable Local CLI & MCP in the app's Settings, install the CLI, and point your MCP client at the whispernotes command with the mcp argument over stdio.
Before you install
The server can create new transcripts and write them to your local history, and it reads transcript text and local audio or video files you point it at. It runs over a local Unix socket with 0600 permissions and is off until you enable it; there is no network endpoint. MCP clients ask for approval before each tool call.

Installation

In SourceWeft

  1. Open Whispernotes in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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:

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

ToolParametersReturns
list_transcriptslimit (default 20) · sourceRecent transcripts with ids, dates, titles
search_transcriptsquery (required) · limitFull-text matches with snippets
get_transcriptid (required) · timestamps · speakers · max_chars · offsetOne transcript's text
get_latest_transcripttimestamps · speakersYour most recent transcript
transcribe_filepath (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 statusWhisperNotes 1.5.5 (340) · SenseVoice Small · ready · 3081 notes
$ whispernotes list --limit 39f3c21a8  2026-08-01 09:14  0:42   meeting   Weekly sync — pricing reviewb2d84e07  2026-07-31 18:03  12:26  recorded  Idea dump on the walk home5a1f9c33  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
CommandOptionsWhat it does
status—App version, active model, readiness, note count
list--limit N · --source T · --jsonRecent transcripts, newest first
search <query>--limit N · --jsonFull-text search across your history, with snippets
show [id or latest]--timestamps · --speakers · --max-chars N · --offset N · --jsonPrint one transcript (defaults to latest)
transcribe <file>--jsonTranscribe an audio or video file, save it to history
export--format txt or md · --output-dir DIR · --source T · --limit N · --audio · --speakersBatch-export transcripts, optionally copying the audio alongside
modelslist · select <id>List or switch models: parakeet, sensevoice, whisper-small, whisper-large-v3-turbo
languagelist · 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

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.

Source: README.md at commit fbac2d2

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts