Apple Notes on Steroids
This server provides full-fidelity Apple Notes management—offering higher-quality read/write than Apple's native tools—through an MCP-compatible interface.
Folder & Note Management: List folders with note counts, list notes (newest first, filterable by folder/limit), and search by title or title+body.
Reading Notes & Attachments: Retrieve notes by ID or title as Markdown (including checkboxes, highlights, quotes, links) or HTML. List all attachments (images, drawings, files) and fetch individual attachments by index (drawings render as images).
Writing & Editing: Create notes from Markdown with true paragraph styles (headings, checklists, code blocks) and attachments. Append Markdown to existing notes without disturbing content, or replace the entire body (optionally change title).
Sync & File I/O: Sync a folder of Markdown files with Apple Notes using frontmatter (
push,pull,off); preview operations with dry-run (sync_status). Export notes to.mdfiles with linked media, and import.mdfiles as new notes with embedded attachments.Rich Formatting: Handles bold, italic, strikethrough, underline, inline code, links, Wikilinks, nested lists, tables, code fences, block quotes, highlights, checklists, horizontal rules, and embedded images/files—converted to/from native styles.
Safety & Design: No delete tool; deletions never propagate. Locked notes are handled gracefully (placeholders or errors). Ambiguous names return candidates instead of guessing. Excludes "Recently Deleted". All writes go through Apple Notes securely.
Provides tools for reading, searching, writing, and syncing Apple Notes, including support for attachments, rich formatting, and Markdown-based synchronization.
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 on Steroids search notes for 'project ideas'"
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 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:
Grant | Buys | Needed |
Automation | talking to Notes at all | always, prompted on first run |
Accessibility | true styles and attachments on write | optional |
Full Disk Access | reading Notes' own store: checked state, quotes, link targets, highlights. Also how a note holding attachments is safely updated, since the store says where they sit | optional |
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
Install
No terminal needed.
Claude Desktop. Download the .mcpb from the latest release, double-click it, install.
ChatGPT. add marketplace krisxsee/apple-notes-on-steroids in Plugins.
Claude Code / Codex. It is a plugin:
claude plugin marketplace add krisxsee/apple-notes-on-steroids
claude plugin install apple-notes-on-steroidsConnect
Any MCP client that runs local stdio servers works: Cursor, Zed, Codex CLI 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"] } } }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 verifyCreates 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
Tool | What it does |
| Every folder with path and note count. |
| Notes, newest first. Optional |
| Titles by default; |
| One note by |
| New note from a Markdown body. |
| Adds to the end. |
| Replaces a note's body, keeping its attachments. |
| What a note carries besides text, one entry per mark and in the same order. |
| One attachment as an image, by index. Drawings come back as Notes' own render. |
| One pass over a folder of Markdown files. |
| Writes a note to a new |
| Creates a note from a |
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.
Feature | State |
Bold, italic, strikethrough, underline | both ways |
Inline code | both ways, at the size of the line around it |
Links, bare and labelled | both ways |
Nested bullet and numbered lists | both ways, four spaces per level |
Tables | both ways |
Headings | both ways. |
Code fences | both ways. Notes cannot hold the language tag, but a pull keeps the one the file already has |
Block quote | both ways, single level, which is all Notes has |
| both ways, orange, with inline code in mint so the two never read alike |
| both ways, checked state included |
Horizontal rule | both ways, written as em dashes because Notes has no rule |
Images, drawings, scans, any file | read fully; written by pasting the file, since the importer cannot make one |
| a real note-link pill when the name matches exactly one note, literal text otherwise, so it becomes a link the day that note exists. Pulled back as |
Callouts, footnotes | plain text, no Notes equivalent |
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.
| Direction | What happens |
| file → note | the note's body is replaced from the file |
| file ← note | the file's body is replaced from the note, media included |
| paused | nothing |
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. One guard: a pull that finds the file edited since the last pull refuses and reports it conflicted, both sides left standing; merge, push once, flip back. .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.
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 testnpm run verify covers what only macOS can answer.
Available Tools
13 toolsappend_noteA
Append to the end of an existing note. The text is Markdown, like create_note's body. The rest of the note is untouched: the fragment is pasted at the caret, so the note's own styles and attachments stay as they are.
Inputs: text (required), id, name, folder, +1 more.
create_noteA
Create a new note. Title becomes the first line. The body is Markdown: inline styles, links, lists, tables, code fences, quotes, ==highlights==, and '- [ ]' checklists are converted.
Inputs: body (required), title (required), attach, folder, +2 more.
export_noteA
Write an existing note to a new Markdown file, with its images, scans and drawings written beside it and linked. The one way attachment bytes reach disk. Rewrites a file it wrote before, refuses any other existing file rather than overwriting it. The file is stamped for pull, so later passes keep it up to date.
Inputs: id, dir, file, name, +1 more.
get_attachmentA
Fetch one attachment of a note by its index in list_attachments. Bytes as Notes holds them, under their own name and type. A drawing has no original, so it comes back as the picture Notes renders of it, which is the only form it exists in.
Inputs: index (required), id, name, folder.
get_noteA
Read one note by id (preferred) or by title. The body comes back as Markdown and never repeats the title, which is already the note's name. The default reads the note's own store, so checked boxes, block quotes, link targets and highlights come back intact; rich:false means the store was out of reach and the body degraded to the exported HTML, which carries none of those. format=html returns the raw HTML. Attachments appear as placeholder marks, never bytes: to copy a note to disk or a vault, use export_note, which writes the images as files too.
Inputs: id, name, folder, format.
import_noteA
Create a new note from a Markdown file. Its image links become real attachments. Creates only: a name that already exists in Notes is refused, so nothing is overwritten.
Inputs: file (required), dir, folder, create_folder.
list_attachmentsA
What a note carries besides text: images, scans, drawings, files. One entry per mark in the note's Markdown, in the same order, so mark n and attachment n are the same thing. A table is not listed: its mark became the pipe rows in the body. Use get_attachment to look at one.
Inputs: id, name, folder.
list_foldersA
List every Apple Notes folder with its path and note count.
Inputs: no named parameters.
list_notesA
List notes, newest first. Optionally scoped to one folder. Trash is excluded.
Inputs: limit, folder.
search_notesA
Search notes by title, or by title and body with search_body=true (slower, capped scope). total is how many matched, notes the first limit of them, whichever mode.
Inputs: query (required), limit, folder, search_body.
sync_nowA
One pass over a folder of .md files, one direction per file. A file opts in with frontmatter apple-note-sync: push sends the file into the note, pull brings the note into the file, off pauses. The file's own name says which note, and it must match exactly one: a name matching none or several is reported and neither side is touched. Rename the note in Notes and the pair is lost until the file is renamed to match. Pass folder to mirror a whole Notes folder: notes there with no file yet are created as pull files, attachments written beside them, so one call covers everything. Deletions never propagate.
Inputs: dir, folder, true_styles.
sync_statusA
Dry-run of sync_now: reports what would be pushed, pulled or created, without writing anything.
Inputs: dir, folder.
update_noteA
Replace a note's body. Destructive for that note: the old body is overwritten. Title is kept unless a new one is given. The body is Markdown, like create_note.
Inputs: body (required), id, name, title, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools are cleanly separated by resource and action, and list/search/read/write distinctions are clear. The only real ambiguity is among export_note, import_note, and sync_now, which all move markdown/attachments between Notes and disk, so agents must carefully compare one-off conversion vs batch sync.
The dominant verb_noun pattern (list_notes, get_attachment, create_note, update_note, export_note) is consistent and readable. sync_now and sync_status are the only slight deviations, but they still read as a paired sync family rather than arbitrary names.
At 13 tools, the server is well within the ideal scope and has no redundant entries. Each tool addresses a distinct operation: reading, writing, searching, attachments, import/export, or sync.
The content lifecycle is mostly covered with list/search/get/create/append/update and strong attachment/sync support. However, there is no delete/trash tool and no folder creation/move or ability to create a note in a chosen folder, which are notable gaps. These omissions create dead ends for cleanup and organizational workflows.
Maintenance
Related MCP Connectors
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Free Markdown notes app, Mac and iPhone. Sync ($5.99/mo) adds a personal MCP endpoint for your AI.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAn MCP server for Apple Notes that enables semantic search and full CRUD operations through natural language.242 npm7MIT
- AlicenseAqualityDmaintenanceComprehensive Apple Notes MCP server for local macOS note management.147,035 npmMIT
- AlicenseNot gradedqualityDmaintenanceMCP server for macOS that enables creating, reading, and searching Apple Notes programmatically through tools like find, get by title or ID, and create.7,035 npmMIT
- AlicenseAqualityBmaintenanceAn MCP server that enables LLM agents to list, read, create, update, delete, and search Apple Notes on macOS.613 npmAGPL 3.0