apple-notes-mcp

An MCP (Model Context Protocol) server that lets AI assistants like Claude read, search, and create notes in Apple Notes on macOS.

It talks to Notes.app via JXA (JavaScript for Automation) through osascript — no private APIs, no database hacks, and it works with iCloud-synced notes.

Requirements

• macOS (tested on macOS 14+)
• Node.js >= 18
• Apple Notes.app

Setup

No clone, no build. Your MCP client downloads and runs the server on demand via npx.

Claude Code

claude mcp add apple-notes -- npx -y @simantaturja/apple-notes-mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "@simantaturja/apple-notes-mcp"]
    }
  }
}

Restart your client. The first call pulls the package from npm (cached afterward) — see Automation permission for the one-time macOS prompt.

Install from source

For development or to run a local build instead of the published package:

git clone https://github.com/simantaturja/apple-notes-mcp.git
cd apple-notes-mcp
npm install   # builds automatically via the `prepare` hook

Then point your client at the built entry, e.g. for Claude Code:

claude mcp add apple-notes -- node /absolute/path/to/apple-notes-mcp/dist/index.js

Environment variables

| Variable | Default | Purpose | |----------|---------|---------| | APPLE_NOTES_TRASH_FOLDER | Recently Deleted | Name of the special trash folder. macOS localizes this name; set it to your locale's name (e.g. Nylig slettet on Norwegian) so deleted notes are correctly excluded from list_notes/search_notes. |

Set it in your MCP client config, e.g. for Claude Desktop:

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "@simantaturja/apple-notes-mcp"],
      "env": { "APPLE_NOTES_TRASH_FOLDER": "Nylig slettet" }
    }
  }
}

Automation permission

The first time a tool runs, macOS will prompt:

"node" wants access to control "Notes".

Click Allow. If you accidentally denied it, re-enable under System Settings → Privacy & Security → Automation.

Tools

| Tool | Description | |------|-------------| | list_folders | List all folders with note counts | | list_notes | List notes (most recently modified first), optionally filtered by folder. Params: folder?, limit (1–200, default 25) | | search_notes | Case-insensitive search in note titles and bodies. Params: query, limit (1–100, default 20), scope (all|title, default all) | | get_note | Read a note's content by id (short or full, preferred) or exact title. Param max_chars (default 10000) truncates long bodies | | create_note | Create a note. Params: title, body (plain text or HTML), folder? | | update_note | Replace or append to a note's body, optionally rename. Params: id/title, body, mode (replace|append, default replace), new_title? | | delete_note | Delete a note (moved to Recently Deleted, recoverable ~30 days). Params: id/title |

Example prompts

• "List my Apple Notes folders"
• "Show my 10 most recent notes"
• "Search my notes for 'tax return'"
• "Read the note titled 'Meeting agenda'"
• "Create a note called 'Groceries' with milk, eggs, bread in the Shopping folder"
• "Add 'butter' to my Groceries note"
• "Delete the note titled 'Old draft'"

Notes on create_note

• Plain-text bodies are HTML-escaped and line breaks are preserved.
• If the body starts with <, it is treated as raw HTML (Notes bodies are HTML). Notes.app sanitizes what it stores, but only pass HTML you trust. Bear in mind the body usually comes from the AI model, so treat it as untrusted: a prompt-injected model could emit arbitrary HTML here. Plain-text bodies are always escaped, so this only applies to bodies you (or the model) deliberately start with <.
• The title is rendered as the note's first line (<h1>), which Notes uses as the note name.

Development

npm run dev    # tsc --watch
npm start      # run the built server (stdio transport)

Project layout

src/
  index.ts          entry point — wires transport, registers tools
  jxa.ts            runs JXA scripts via osascript (argv-safe)
  snippets.ts       shared JXA code (HTML escaping, note resolution, folder map)
  helpers.ts        result wrappers, id-prefix factoring, body truncation
  cache.ts          in-process plaintext + folder-map caches
  types.ts          NoteSummary / NoteDetail
  tools/read.ts     list_folders, list_notes, search_notes, get_note
  tools/write.ts    create_note, update_note, delete_note
test/               node:test suites (see below)

Tests

npm test               # fast unit tests — no Notes.app, no permissions needed
npm run test:integration   # full lifecycle against real Notes.app (creates + deletes a test note)

Unit tests run pure logic — id factoring, body truncation, the JXA HTML/resolver snippets (evaluated directly in Node), and cache invalidation with an injected fetcher — so they need no macOS automation permission and run in ~250 ms.

The integration test drives the built server over real JSON-RPC and exercises create → search → update → get → delete. It is opt-in (gated on APPLE_NOTES_IT=1, set by the script) because it touches your real Notes library; the test note it creates is deleted (moved to Recently Deleted) at the end.

You can also smoke-test by piping JSON-RPC to the server:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js

Security

• User input is passed to JXA via argv, never interpolated into the script — no script injection.
• Scripts run through execFile (no shell), with a 120s timeout and bounded output buffer.
• Note titles and plain-text bodies are HTML-escaped before being written to Notes.
• delete_note moves notes to Recently Deleted (recoverable for ~30 days) — it never permanently erases.
• Title-based update/delete refuses to act when multiple notes share the title (use id).
• Notes in Recently Deleted are excluded from list_notes/search_notes (pass folder: "Recently Deleted" to list them explicitly). Note: the folder is matched by name (default Recently Deleted); on a non-English macOS locale, set APPLE_NOTES_TRASH_FOLDER (see Environment variables) so the exclusion applies.
• Everything runs locally; no note content leaves your machine except through the MCP client you connect.

Why it's fast

All numbers below measured on a real library (436 notes, 28 folders, Apple Silicon).

1. Bulk Apple Events instead of per-note calls. Every JXA property access (note.name()) is one Apple Event — an IPC round trip to Notes.app costing tens of milliseconds. A naive loop over notes pays notes × properties round trips. This server instead fetches each property for all notes in a single event (Notes.notes.name() returns every name at once):

| Approach | Measured | |---|---| | Naive per-note loop, 25 notes | 1,784 ms | | Bulk fetch, all 436 notes | 47 ms |

Per note that is roughly 650× faster, and it's why end-to-end tool calls stay in the 300–550 ms range including Node and osascript process startup.

2. Incremental plaintext cache. Note bodies are cached in-process, keyed by note id and validated against each note's modificationDate — so a cache entry self-invalidates the moment a note changes, and deletes are evicted automatically. Each search after the first only re-fetches notes that actually changed:

| Search | Measured | |---|---| | First search of a session (cold cache) | ~430 ms | | Every following search (warm cache) | ~180 ms | | Title-only search (scope: "title") | ~160 ms |

There is no staleness window: metadata is checked live on every call, so results are always current — unlike index-based servers that serve stale results between re-indexing runs.

3. No index, no embeddings, no warm-up. RAG-based servers (LanceDB + embedding models) need a ~200 MB model download, an initial indexing pass over every note, and re-indexing when notes change — and can serve stale results between re-indexes. This server queries Notes.app live: zero setup, zero warm-up, never stale.

4. Minimal runtime. Two runtime dependencies (MCP SDK, zod). No Bun, no transformers, no vector DB. Server is up and answering in ~125 ms.

5. No Full Disk Access / SQLite parsing. Servers that read the Notes SQLite database need Full Disk Access and break when Apple changes the schema. JXA is the supported automation interface.

Fit guidance: designed for libraries up to a few thousand notes. The cold-cache search grows with library size (one bulk body fetch); warm searches stay flat. At many thousands of large notes, an indexed/semantic-search server will answer the first search faster — in exchange for the indexing machinery above.

Why it consumes few tokens

Tool schemas load into the model's context every session; tool results enter it on every call. Both are kept deliberately small:

• Lean schema — 7 tools ≈ 1,050 tokens total (~150/tool). Feature-heavy servers ship 15–20+ tools and several times that on every single session.
• Compact JSON — no pretty-printing (~18% smaller).
• Factored id prefix — note ids share a 55-char x-coredata://UUID/ICNote/ prefix; list/search return it once as idPrefix with short per-note ids (p634). All tools accept either form.
• Bounded responses — get_note caps bodies at max_chars (default 10,000 chars ≈ 2,500 tokens) with a truncation marker telling the model exactly how to fetch the rest. A single huge note can never flood the context.
• No noise — empty folder fields omitted, dates without milliseconds, plaintext bodies (never raw HTML, which some servers return at 3–10× the token cost).

Measured: list_notes of 25 notes ≈ 2,150 chars (~540 tokens) — versus 925 chars for just 5 notes before these optimizations (~47% reduction at equal content).

License

MIT