# Whisper Notes CLI & MCP Server

Drive Whisper Notes from your terminal, or let Claude and other AI assistants search, read, and create transcripts directly. 100% on-device — your audio and transcripts never leave your Mac.

## Set up

1. Download [Whisper Notes for Mac](https://dl.whispernotes.app/WhisperNotes-latest.dmg) **1.5.5 or later** — DMG version (not Mac App Store).
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.

> The examples below use the short alias `wn`. If `wn` is already taken on your Mac (e.g. by WordNet), the full command `whispernotes` works identically.

## Use the CLI

```bash
$ 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](#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:

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

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

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

```bash
# 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

| 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 as files, 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 (for AI clients, not humans) |
| `version` · `help` | — | CLI version · usage |

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

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

## Privacy & security

- Transport is a Unix domain socket at `~/Library/Application Support/WhisperNotes/api.sock` 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` — install the command-line tool from **Settings → Integrations** in the app, then open a new terminal window (both `whispernotes` and `wn` should work).
- **"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 1.5.5 or later via the in-app updater or the [latest DMG](https://dl.whispernotes.app/WhisperNotes-latest.dmg).
- **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 (DMG)](https://dl.whispernotes.app/WhisperNotes-latest.dmg)
- [Changelog](https://whispernotes.app/changelog)
- [Privacy policy](https://whispernotes.app/privacy)
- Raw markdown of this page for agents: [whispernotes.app/cli-mcp.md](https://whispernotes.app/cli-mcp.md)
- Questions or ideas: support@whispernotes.app