Apple Notes on Steroids

An MCP server for Apple Notes. Read, search, write and sync notes at full fidelity, including the styles Apple's own import path throws away.

Requirements

macOS with Apple Notes, Node 18 or newer, and up to three permission grants:

The server works with Automation alone, at reduced fidelity, and says so in its answers. The optional two are granted in System Settings, Privacy & Security, to the exact app running the server, so they need re-granting after that app updates.

Related MCP server: Apple Notes MCP

Connect

Any MCP client that runs local stdio servers works: Claude Code, Claude Desktop, Codex CLI, Cursor and the rest. The one constraint is that the server must run on the Mac where Notes lives.

{ "mcpServers": { "apple-notes-on-steroids": { "command": "npx", "args": ["-y", "github:krisxsee/apple-notes-on-steroids-mcp"] } } }

In Claude Code it is also a plugin:

claude plugin marketplace add krisxsee/apple-notes-on-steroids-mcp
claude plugin install apple-notes-on-steroids

In Claude Desktop, no terminal needed: download the .mcpb from the latest release, double-click it, install.

From source: npm install && npm run build, then point the client at dist/index.js. To sync, set APPLE_NOTES_MD_DIR to the folder of .md files, or pass dir per call.

Verify

npm run verify

Creates one note in "MCP Tests" holding every style the server claims to write, reads it back character for character, and never touches a note that existed before.

Tools

No delete tool, on purpose.

Formatting

Bodies are Markdown, both ways. Two write paths produce a note: the HTML importer takes everything it can, instantly and silently, and a pasteboard hand-off supplies what it cannot.

Sync

One direction per file, and Notes is the centre. A file's own name says which note it belongs to, and one property says which way it flows.

A pass only touches notes that already exist. A name matching no note, or more than one, is reported and neither side is written. Rename a note and the pair is lost until you rename the file to match.

One direction cannot have a conflict, so there is no conflict resolution. .apple-notes-sync.json is a cache used only to skip work; delete it and the next pass reaches the same place.

Media pulls in beside the .md file that links it, with ordinary Markdown. A push reconciles those links against the note: a link added attaches the file, one removed detaches it. A drawing is never removed, because nothing outside Notes reads its strokes.

export_note and import_note create the other side. Both refuse to overwrite.

Safety

• No delete tool.

• Sync never propagates deletions.

• Notes in "Recently Deleted" are excluded from listings, search and folder resolution, and are never written to.

• Locked notes: metadata reads, body reads return a placeholder, writes fail with LOCKED.

• Ambiguous names return candidates rather than a guess.

• The live check works only on notes it created.

• The store is opened read-only. Writing goes through Notes itself, always.

Design

Four ideas hold it together. The source map lives in CLAUDE.md.

Nothing is addressed by position. A position is a second model of the note kept beside the note, and it drifts. Text is what both sides can see.

The store is the only witness. A paste changes what a paragraph is and not one character of what it says, so the editor proves nothing.

Losing state must never read as having no state. Empty is a fact about the world; unreadable is a fact about this pass. Conflating them lets one side overwrite the other.

Never destroy what cannot be put back. An image removed still exists as a file. A drawing does not.

Development

npm test

npm run verify covers what only macOS can answer.