apple-notes-mcp
This server lets AI assistants read, search, create, update, and delete notes in Apple Notes on macOS. Key capabilities include:
List Folders — Retrieve all Apple Notes folders with their note counts.
List Notes — Browse notes sorted by most recently modified (limit 1–200, default 25), optionally filtered by folder.
Search Notes — Case-insensitive search across note titles and/or bodies, with configurable result limits and scope (
allortitleonly).Read a Note — Fetch full note content by ID or exact title, with a configurable character limit (default 10,000 chars) to avoid flooding context.
Create a Note — Add a new note with a title and plain-text or HTML body, optionally placed in a specific folder.
Update a Note — Modify an existing note by replacing or appending to its body, and optionally rename it.
Delete a Note — Move a note to "Recently Deleted" (recoverable for ~30 days) by ID or exact title.
Provides tools for reading, searching, and creating notes in Apple Notes on macOS.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@apple-notes-mcp Show my 10 most recent notes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Published on npm as @simantaturja/apple-notes-mcp — no clone or build needed, your MCP client runs it via npx.
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
Related MCP server: Apple Notes MCP Server
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-mcpClaude 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` hookThen 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.jsEnvironment variables
Variable | Default | Purpose |
|
| Name of the special trash folder. macOS localizes this name; set it to your locale's name (e.g. |
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 all folders with note counts |
| List notes (most recently modified first), optionally filtered by folder. Params: |
| Case-insensitive search in note titles and bodies. Params: |
| Read a note's content by |
| Create a note. Params: |
| Replace or append to a note's body, optionally rename. Params: |
| Delete a note (moved to Recently Deleted, recoverable ~30 days). Params: |
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.jsSecurity
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_notemoves 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(passfolder: "Recently Deleted"to list them explicitly). Note: the folder is matched by name (defaultRecently Deleted); on a non-English macOS locale, setAPPLE_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 ( | ~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 asidPrefixwith short per-note ids (p634). All tools accept either form.Bounded responses —
get_notecaps bodies atmax_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
Available Tools
7 toolscreate_noteA
Create a new note in Apple Notes. Body accepts plain text (line breaks preserved) or HTML.
Inputs: title (required), body, folder.
delete_noteA
Delete an Apple Note. The note is moved to Recently Deleted (recoverable for ~30 days), not permanently erased. Locate by id (preferred) or exact title.
Inputs: id, title.
get_noteA
Read the full content of an Apple Note by its id (preferred, from list_notes/search_notes) or exact title.
Inputs: id, title, max_chars.
list_foldersA
List all folders in Apple Notes with their note counts.
Inputs: no named parameters.
list_notesA
List notes in Apple Notes, most recently modified first. Optionally filter by folder name. Returns id, title, folder, and modification date.
Inputs: folder, limit.
search_notesA
Search Apple Notes by text in the note title or body. Returns matching notes (id, title, folder, modification date).
Inputs: query (required), limit, scope.
update_noteA
Update an Apple Note: replace its body or append to it. Locate by id (preferred) or exact title.
Inputs: body (required), id, title, mode, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a distinct purpose: CRUD operations for notes, listing/searching notes, and listing folders. No functional overlap.
All tools follow a consistent verb_noun pattern in snake_case (e.g., create_note, list_folders, search_notes). No deviations.
7 tools is appropriate for an Apple Notes MCP server, covering all essential operations without unnecessary redundancy.
Covers full CRUD for notes, search, and folder listing. Minor gap: no tool to create or rename folders, but core note workflows are complete.
Related MCP Connectors
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Notes and actions in one app. Let Claude or ChatGPT read and update them.
Save, search and edit your private notes by talking to your AI assistant.
Read and write the notes and folders of your Grape account, the AI note-taking app.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables interaction with Apple Notes on macOS through AppleScript, allowing users to list, search, read, create, update, and delete notes across accounts and folders.71-
- AlicenseAqualityDmaintenanceEnables AI assistants to read, create, search, update, and delete Apple Notes through natural language conversation, using JXA to communicate directly with the Notes app.830ISC
- AlicenseAqualityDmaintenanceEnables AI clients to search, read, create, update, move, and delete Apple Notes on macOS via AppleScript automation.102MIT

simplenote-mcpofficial
AlicenseNot gradedqualityBmaintenanceEnables AI tools to read and optionally write Simplenote notes via local database or API, supporting offline use on macOS.369 npm33MIT