Apple Notes MCP

Let Claude, Cursor, or Codex search and edit your Apple Notes — by meaning, entirely on your Mac.

You  ▸ What did I decide about the pricing model back in spring?

Claude ▸ [search-notes] "Pricing v3" (Apr 14) — you settled on usage-based
         with a floor, after rejecting per-seat in "Pricing v2".

You didn't name the note. There's no folder called "pricing." No API key was used, and nothing left your laptop.

Features

Search finds notes you can't remember the words for

Every note is embedded on-device with all-MiniLM-L6-v2 into LanceDB, alongside a full-text index. A query runs both and fuses the two rankings with Reciprocal Rank Fusion.

Why both: keyword search fails when you remember the idea but not the phrasing. Vector search fails on exact strings — an error code, an invoice number, a person's name. Fusing them ranks a note that scores mid-range on both above one that spikes on only one, so you don't have to guess which kind of query you're making.

Writes that can't quietly destroy a note

Six write tools, with three guarantees:

Reading an untrusted note can't execute code

The obvious way to drive Apple Notes is to interpolate a title into a script:

const title = "${title}"   // ← arbitrary code execution

A title containing " closes that literal, and the rest runs as JavaScript for Automation — shell commands, file reads, exfiltration. Note titles are not trusted input: they arrive from shared notes, mail-to-Notes, imports, and sync from other devices.

This server removes the vulnerability class instead of escaping around it. The JXA scripts are static files shipped in the package, titles and bodies are passed as argv and read inside run(argv), and subprocess always runs with an argument list and shell=False. No user-controlled text ever enters any program source. Full review in SECURITY.md.

Fully local

No API keys, no account, no telemetry. The only network request in the tool's life is a one-time ~90 MB model download — after that it works on a plane.

Built to survive macOS updates

Notes are read through Apple's automation API, not by parsing the private NoteStore.sqlite. Direct sqlite reads are faster, but Apple reshapes that schema between releases and stores bodies as gzipped protobuf. Via the automation API, macOS's own permission prompt is the consent gate and an OS update doesn't silently corrupt your index.

Folder scoping everywhere

get-note, update-note, append-note, backup-note, and move-note all take an optional folder. Pass it and same-titled notes in other folders or iCloud accounts stop shadowing your target.

Related MCP server: MCP Apple Notes

Requirements

macOS (Apple Notes and osascript are macOS-only) · Python 3.10+ · ~500 MB disk for the model and its torch dependency.

Setup

1. Install

uv tool install applenotes-mcp

brew install uv && uv tool install applenotes-mcp     # recommended, isolated

# or pip, inside a virtualenv
python3 -m venv ~/.venvs/notes && ~/.venvs/notes/bin/pip install applenotes-mcp

2. Register it with your client

Every client runs the same command, uvx applenotes-mcp. Find your row:

Cursor, Claude Desktop, and Windsurf take this exact JSON:

{
  "mcpServers": {
    "apple-notes": { "command": "uvx", "args": ["applenotes-mcp"] }
  }
}

Codex uses TOML:

[mcp_servers.apple-notes]
command = "uvx"
args = ["applenotes-mcp"]

VS Code nests under servers, Zed under context_servers. Ready-to-paste files for every client are in integrations/.

Claude Code plugin

One step for the server plus an apple-notes skill:

/plugin marketplace add ashishakkumar/apple-notes-mcp
/plugin install apple-notes-mcp

3. Teach your agent to use it well

Optional, but the highest-leverage step. Step 2 connects the tools; this explains when to reach for them — search before asking which note, why append-note beats update-note, what to do with an ambiguous title. Without it, agents tend to ask you for a note title instead of just searching.

4. Grant permission and index

1. Ask your assistant: "Index my Apple Notes."

2. macOS prompts for permission to control Notes. Approve it — nothing works until you do. (Later: System Settings → Privacy & Security → Automation.)

3. The first run downloads the model once, then embeds every note. Seconds for a few hundred notes, a couple of minutes for thousands.

4. Ask something real: "What did I write about the Q3 budget?"

Re-run index-notes after adding or editing notes — the index is a snapshot, not a live view.

claude mcp list    # Claude Code

# any client — does the server start and speak MCP?
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
  | uvx applenotes-mcp

A JSON reply naming apple-notes means the server is fine, and any remaining problem is client config.

Tools

Read

Write — each snapshots the old body to ~/.local/share/apple-notes-mcp/backups/ first.

Bodies are HTML on a single line, capped at 2 MB.

What to know before indexing

• Indexing reads every note in full. That's the point, but be deliberate.

• The index is unencrypted at ~/.mcp-apple-notes/data, protected only by file permissions and FileVault. Treat it as sensitive as your notes.

• Prompt injection is inherent to RAG. A note can contain text aimed at the assistant reading it. No MCP server can neutralize that.

Purge everything: rm -rf ~/.mcp-apple-notes ~/.local/share/apple-notes-mcp

Troubleshooting

Bonus: conversation-tag for Ghostty

plugin/ is an optional macOS + Ghostty extra: it tags each terminal tab with a pixel-art sprite and title pulled from today's Apple Notes todo list, so six parallel Claude sessions stop looking identical. Built on this server, installed via its own install.sh (it writes a GPU shader, which the plugin system can't do). See plugin/README.md.

Development

git clone https://github.com/ashishakkumar/apple-notes-mcp && cd apple-notes-mcp
uv venv
uv pip install --group test        # pytest + light runtime deps
uv pip install -e . --no-deps      # skips torch; the tests stub the embedder
uv run pytest

The suite stubs _run_jxa, the single boundary to macOS, so it runs on any platform and covers injection safety, UTF-8 byte caps, ambiguity refusal, backup-before-mutate ordering, path traversal in backup filenames, and RRF fusion. CI additionally exercises mcp 1.x and 2.x and completes a real stdio handshake.

Credits

Python port of mcp-apple-notes by Rafal Wilinski, rewritten to close the injection issues in the original and add write tools, backups, and folder scoping.

MIT — see LICENSE.