Apple Notes

@mgcrea/mcp-apple-notes

Model Context Protocol server for the macOS Apple Notes app.

Unofficial. Not affiliated with Apple. It drives the Notes app that is already on your Mac.

Two lanes

• Apple Events lane — accounts, folders, bodies, and every mutation. Always the authority: after a write, the result is what Notes re-read.
• Index lane — read-only SQLite over NoteStore.sqlite, for search and metadata at a scale Apple Events cannot reach. Needs Full Disk Access.

Unlike Mail, the Apple Events lane alone is a working server. Measured on a 921-note library, a full-text search takes 97 ms — against the 74 s that forced Mail onto its index. So you can install this, use it, and only then decide whether to grant Full Disk Access.

It does not scale for ever: there is no index behind it, so every query pays the full cost again. The wall is around 5–10k notes. apple_notes_diagnostics tells you which lane is answering.

Permission	Needed for	Without it
Automation → Notes	everything	nothing works; you get a -1743 error
Full Disk Access	search at scale, save_attachment	the server still runs, on the Apple Events lane

Neither is granted to Notes.app — it is the reader that needs permission.

Tools

Read: diagnostics, list_accounts, list_folders, list_notes, search_notes, get_note, list_attachments, save_attachment.

Write, registered only when APPLE_NOTES_ALLOW_WRITES=1 — with the flag off they are invisible to the model, not merely refused: create_note, update_note, move_note, delete_notes, add_attachment.

add_attachment is the only way to put an image in a note. An <img> tag in a note's body creates an attachment whose bytes Notes never loads — see docs/notes.md.

Configuration

Variable	Default
APPLE_NOTES_ALLOW_WRITES	off	Register the mutating tools.
APPLE_NOTES_ACCOUNTS	all	Read-side allowlist, comma-separated.
APPLE_NOTES_INDEX_MODE	auto	auto | ro | immutable | off.
APPLE_NOTES_STORE	auto	Explicit NoteStore.sqlite path.
APPLE_NOTES_SEARCH_CACHE_TTL_MS	60000	How long the body corpus stays warm.
APPLE_NOTES_ATTACHMENT_DIR	~/Downloads	The only directory attachments may be saved into.
APPLE_NOTES_BODY_MAX_BYTES	262144	Body truncation, to protect the context window.
APPLE_NOTES_OSASCRIPT_TIMEOUT_MS	30000	Sized for the first-run permission prompt.

Notes that will bite you

• Notes takes a note's title from the first line of its body. Setting name is silently ignored, so create_note prepends the title as a heading instead.
• Password-protected notes cannot be read at all. Their text is AES ciphertext at rest, which is why ZICNOTEDATA carries crypto columns; no permission makes it readable.
• Folders nest. A folder map has to recurse even if your own library happens to be flat.
• Search caches on a TTL, not on invalidation. Checking whether the cache is stale costs more over Apple Events (128 ms) than redoing the scan (97 ms), so bounded staleness is the honest trade. See docs/notes.md.

Licence

MIT.