applenotes-mcp
An MCP server for creating, reading, editing, searching, and organizing Apple Notes with real Notes formatting via Shortcuts/App Intents.
Create formatted notes from markdown with headings, bulleted/numbered lists, tables, block quotes, code blocks, checklists, bold/italic, and local file attachments (images/PDFs).
File notes into existing folders, or create nested folders first; use full paths when folder names are ambiguous.
Read notes back as markdown, preserving checklists, list types, tables, and attachment links where possible.
Edit a note's body via destructive replace: the note is backed up, deleted, and recreated with a new ID and creation date.
Search notes by title or full-text search across title and body, returning IDs, folder, modified date, and snippets.
List all folders, browse a folder's notes and immediate subfolders, and create missing folder paths.
Allows interaction with Apple Notes app, enabling creation, reading, editing, searching of notes with proper formatting, including headings, lists, tables, checklists, and file attachments.
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., "@applenotes-mcp search my 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.
applenotes-mcp
An MCP server for Apple Notes that writes properly formatted notes with support for headings, bulleted and numbered lists, tables, block quotes, code blocks, checklists, and file attachments (images, PDFs).
Why this exists
Other Apple Notes MCP servers drive Notes using AppleScript, and this results in
a number of significant limitations. Writing a note through AppleScript requires
handing HTML to Notes' importer which ignores the styling and bakes
explicit inline font sizes onto everything it produces.
Headings are bold spans rather than real headings, font sizes are wrong, and tables,
checklists, and attachments cannot be created. Better HTML does not help: for example
an explicit 13px is rewritten to 11px by the importer.
This MCP uses Shortcuts.app instead as the method of writing, driving Notes' own App
Intents and avoiding the HTML importer entirely. The markdown is parsed by Notes itself,
via the interpretAsMarkdown parameter on the Append to Note intent — the same parser as
File > Import Markdown. Notes written this way contain proper formatting.
That parser is markedly better than the Shortcuts Make Rich Text from Markdown action
this used to go through: block quotes, fenced code blocks and horizontal rules survive,
headings land on the right paragraph style, and single-dash table delimiters (| - |) are
accepted. Two workarounds for that older converter — rewriting delimiter rows, and sending
each table as its own chunk so the list after it was not destroyed — are gone.
Using Shortcuts also lets us write the things that AppleScript does not (checklists, attachments, tables...)
Related MCP server: apple-notes-mcp
Requirements
Developed on macOS 26.5, and currently tested on macOS 27.0. The minimum version is not known because it depends on which Notes App Intents are present. Note that macOS 27 removes two capabilities from the default install — see Ticked checkboxes and attachment sizes need the full build under Limitations.
You also need Python 3.13+ and uv.
Permissions
Two macOS permissions must be granted to whichever application runs the server - which is generally your terminal or the Claude Desktop app (i.e. not to Python or to Notes.app).
Full Disk Access (System Settings → Privacy & Security → Full Disk Access). Reading is done straight from Notes' own store at
~/Library/Group Containers/group.com.apple.notes/NoteStore.sqlite, which is protected. Without it the server still runs but degraded.read_notefalls back to AppleScript HTML, andedit_notewill refuse to edit.Automation → Notes (System Settings → Privacy & Security → Automation). Prompted for on the first
osascriptcall.
Setup
uv syncRegister with Claude Code:
claude mcp add applenotes -- uv run --directory /path/to/applenotes_mcp applenotes-mcpOn first use the server generates and signs the bridge shortcut and asks you to import it. This is a one-time confirmation that Shortcuts cannot be automated around: open the file it names and click Add Shortcut, then retry. The same happens if you later update the server and the installed shortcut falls behind — delete the old one and import the new.
Installing the full build
Optional, and only worth it if you want ticked checkboxes (- [x]) or attachment display
sizes (![pic|small]). Everything else works identically on the basic build.
The two actions those need still run perfectly; it is only the Shortcuts app's importer
that rejects them. tools/wfimport.m installs a signed shortcut by talking to WorkflowKit
directly, skipping that check:
clang -fobjc-arc -framework Foundation -o wfimport tools/wfimport.mGenerate the full build, then install it — quit Shortcuts.app first, and delete any existing Notes MCP Bridge so you do not end up with two:
uv run python -c "from applenotes_mcp import bridge; print(bridge.generate_signed_shortcut(full=True))"
./wfimport "$HOME/.local/share/applenotes-mcp/Notes MCP Bridge.shortcut" \
~/Library/Shortcuts/Shortcuts.sqliteUnderstand what you are taking on. This is private Apple SPI writing directly to a
database that syncs to iCloud. It works today and the whole live suite passes against it,
but Apple can change either at any release, and nothing here is supported. Back up
~/Library/Shortcuts/ first. The server tells the two builds apart by a marker inside the
shortcut, so it always knows which capabilities it has, and updating regenerates whichever
build you installed rather than silently downgrading you.
Tools
Tool | Purpose |
| Create a formatted note, attachments and all. Returns its ID. |
| Read a note back as markdown. |
| Replace a note's body. Destructive — see below. |
| Find notes by title. Returns |
| Full-text search over title and body. Same rows as |
| The folders a note can be filed into, as full paths. |
| Browse one folder: its notes (newest first) and immediate subfolders. |
| Create a folder, making any missing parents. |
The tools are annotated (readOnlyHint, destructiveHint) and the server contains instructions to explain the tools to your model.
Limitations
Editing is destructive. Due to a variety of Apple-based limitations, editing involves reading the source note, creating an edited copy, and deleting the original. This means that:
the note gets a new internal ID and a new creation date
this messes up Shared Notes
If the note's structure cannot be properly read from NoteStore then the edit is
refused rather than run from the degraded HTML. Still, every edit writes a JSON
backup to ~/.local/share/applenotes-mcp/backups/ first, and
the original also lands in Notes' Recently Deleted for 30 days so if anything goes wrong
then you can just fish it out of the bin.
Ticked checkboxes and attachment sizes need the full build. Not because the actions
stopped working, but because macOS 27's Shortcuts will no longer import a workflow that
contains them. com.apple.Notes.SetChecklistItemCheckedLinkActionv2 and
com.apple.Notes.SetAttachmentSizeLinkAction are both refused, with only "This shortcut
can't be imported because it contains features not supported on this device" and a log line
reading Refusing to import shortcut with reasons: <private>. Every other Notes action the
bridge uses imports fine.
The default (basic) build therefore leaves them out: - [x] writes an unticked checkbox
and  attaches at the default size. Neither is silent — both are reported as
WARNING lines after the returned note ID. Reading is unaffected either way: a note ticked
or resized by hand in Notes.app still reads back correctly. To get them back, install the
full build (below). See NOTES.md for how this was narrowed down.
Heading depth is flattened below level 4. Notes' markdown parser maps # to Notes'
Title style, ## to Heading and ### to Subheading, all of which round trip intact.
#### maps to Subheading as well, so #### Foo reads back as ### Foo.
Links gain a trailing slash. Notes.app normalises a bare-host URL, so
https://example.com comes back as https://example.com/.
Inline code becomes a pink highlight. Notes' markdown parser stores `code` as the pink
highlight (AttributeRun field 14 = 2, emphasis_style in other parsers' schemas) rather than as
monospaced text, so it displays in red. Fenced code blocks are real monospaced paragraphs, so use
those instead. Older notes with an inline monospaced font should read back as `code` too,
which means editing them should turn those spans pink.
Fenced code blocks must stay outside lists and block quotes. A nested fence is flattened:
under a list item, each of its lines becomes an ordinary list item at that level, which also
renumbers a numbered list. The note is still written, with a WARNING after its ID. Close the
list, write the fence at the top level, and start the list again.
Highlights mostly revert to normal text. Pink reads back as `code` and so survives an edit,
though it is then indistinguishable from inline code. The other colours are not decoded and are
lost, because the only write route found is the one above.
Attachments show as "PDF Document" (or "Image", etc.), not a title. Notes shows the tile
title from an attachment's ZTITLE field, which it only populates when you add a file through
its own UI. Nothing in the automation surface can set it: the Add File to Note intent leaves
it empty (its name parameter sets only the media filename, which Notes does not display),
there is no rename intent, the attachment entity's name is not writable, and AppleScript cannot
even see intent-created attachments. Label attachments by the surrounding note text instead.
Tests
uv sync
uv run pytestThis will test all the normal code logic, renderers, AppleScript use etc. The test
suite also includes tests/fixtures/*.zdata which are real note protobufs that Notes.app
itself wrote, paired with the AppleScript HTML and the expected markdown.
These can be regenerated with uv run python tests/capture_fixtures.py, which
writes .actual files that you then promote to .expected by hand if everything looks correct.
The suite also includes a set of live round trips which test the entire flow. These create
and delete real notes, so they are off by default. Everything happens in a dedicated
MCP Live Tests folder, which must exist and be empty before the tests start.
APPLENOTES_MCP_LIVE=1 uv run pytest -m liveBoth live and APPLENOTES_MCP_LIVE must be set and both are checked before testing starts.
Licence
MIT — see LICENSE.
Available Tools
8 toolscreate_folderAIdempotent
Create a folder at path, making any missing parent folders along the way.
path is a full path like "Personal/Projects/Roadmap"; each segment that does not exist
yet is created under the one before it (the first under the top level). A path that
already exists is left untouched. This is separate from create_note on purpose:
create_note still REFUSES an unknown folder, so a typo files nothing by surprise --
call this first to make the folder deliberately, then create the note into it.
Folders are addressed by id (built from the store UUID), so nesting under a folder whose name is not unique still works. Refuses if a parent path is itself ambiguous.
Inputs: path (required). Returns: result
create_noteA
Create an Apple Note from markdown, preserving real formatting.
Headings, bullet and numbered lists, tables, bold and italic all survive as real Notes objects -- unlike AppleScript-based servers, which force the whole note to a fixed font size and cannot produce tables at all.
Attachments: a whole-line image  or link [name](/path) whose
target is a LOCAL file (an absolute path or a file:// URL) is attached to the note at
that point, of any byte size. An http(s) link stays an ordinary link. A display size may
be added after a pipe --  -- as small, medium or large.
Args:
title: the note's title -- the bold first line Apple shows in the notes list, not
just metadata. Give it a real, descriptive value. If left blank, it is taken
from the first heading or line of prose in the markdown (never an image).
markdown: the body. Do NOT repeat the title as a # <title> heading at the top --
Notes already shows the title, and a leading one matching title is dropped.
For section headings inside the note use ## and ###: # is Apple's Title
style, so a # heading renders as a second title. ## Foo round-trips as
## Foo; only ### and deeper flatten (to ##).
folder: optional existing folder to file the note under, given as a name or, where
the name is not unique, as a full path like "Personal/Projects/Recipes". Call
list_folders to see what exists; an ambiguous name is rejected, not guessed.
Returns the new note's ID.
Inputs: title (required), markdown (required), folder. Returns: result
edit_noteADestructive
Replace a note's body with new markdown, keeping its title and folder.
IMPORTANT -- this is destructive. Apple provides no way to rewrite a note in place with real formatting, so the note is deleted and recreated: it gets a NEW note ID and a new creation date. The original is backed up to ~/.local/share/applenotes-mcp/backups first.
Attachments are preserved: keep their  / [name](file://...)
lines in the markdown you pass back and they are re-attached; drop a line to remove that
attachment. The one exception is an attachment that is not downloaded locally (evicted
to iCloud) -- the note is refused, since that file cannot be re-attached. The normal flow
is to read_note, edit that markdown, and pass it back here.
Returns the new note's ID.
Inputs: note_id (required), markdown (required), title. Returns: result
list_folderARead-onlyIdempotent
List the notes and immediate subfolders inside folder.
folder is a path (or a name, where unique) as shown by list_folders; an ambiguous
name is rejected rather than guessed at. Subfolders are given as full paths (pass one
back here to descend into it). Notes are listed newest first, one per line, tab-separated
as id, title, modified (YYYY-MM-DD HH:MM), snippet -- the same id that
read_note and edit_note take. This is how to browse the library by structure, where
search_notes/search_note_text find notes by their text.
Inputs: folder (required). Returns: result
list_foldersARead-onlyIdempotent
List the folders a note can be filed into, as full paths, one per line.
create_note can only file a note into a folder that already exists -- it never creates
one -- so call this rather than guessing a folder name. To file into a folder that is not
listed here, call create_folder first.
Paths are shown because folder names are NOT unique: nesting allows both
"Personal/Recipes" and "Personal/Projects/Brewing/Recipes". Pass the full path to
create_note whenever a bare name appears more than once here; an ambiguous name is
rejected rather than guessed at.
Inputs: no named parameters. Returns: result
read_noteARead-onlyIdempotent
Read a note as markdown, for inspecting or editing it.
Reconstructed from Notes' own protobuf, so checklists come back with their ticked
state, and a numbered list is not confused with a bullet list -- neither of which
the HTML AppleScript exports can express. Tables are taken from the HTML, since the
protobuf holds them only as a placeholder. File attachments (images, PDFs) come back
as  / [name](file://...) pointing at the file on disk.
Heading depth is preserved through ##; only ### and deeper are flattened (to ##),
and that is a write-side loss, not a read-side one -- ### Foo was already stored as a
Heading. # is Apple's Title style, so the note's own title reads back as # <title>.
Falls back to the HTML alone if the protobuf cannot be read, which loses checklists;
edit_note refuses to run in that state rather than rewrite from a degraded read.
Inputs: note_id (required). Returns: result
search_notesARead-onlyIdempotent
Find notes whose TITLE contains query, most recently modified first.
Returns one row per match, tab-separated: id, title, folder, modified
(YYYY-MM-DD HH:MM), snippet (a one-line body preview). The id is the only way to
obtain a note ID, which read_note and edit_note both need; the other columns are for
telling apart notes that share a title -- present several to the user by folder and date
rather than guessing which is meant.
This searches TITLES only and is fast. If it returns no matches -- or you are after
notes that mention something rather than are titled after it -- fall back to
search_note_text, which also searches bodies. "no matches" here never means the
content is absent, only that no title contains query.
Inputs: query (required), limit. Returns: result
search_note_textARead-onlyIdempotent
Full-text search: find notes whose TEXT (title and body) contains query.
Same row format as search_notes (id, title, folder, modified, snippet),
most recently modified first. Use this when looking for notes that mention something
rather than notes titled after it; use search_notes when you know the title, as it is
faster. Matching is on the note's plain text, so formatting (checklists, tables) does not
affect what matches.
Inputs: query (required), limit. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Two tool pairs—list_folders/list_folder and search_notes/search_note_text—have similar names but clearly distinct scopes (all folders vs. folder contents; title-only vs. full-text). The remaining tools (create_folder, create_note, read_note, edit_note) are unambiguous. Minor risk of misselection due to name proximity, but descriptions prevent real confusion.
All tool names follow a consistent snake_case verb_noun pattern (list, search, create, read, edit) with objects (folders, notes, folder, note_text). No camelCase or mixed verb styles, so the naming is highly predictable.
Eight tools is well within the ideal 3-15 range for a notes management server. Each tool provides a clear function in note/folder handling without unnecessary redundancy, making the surface appropriately scoped.
The tool set covers create, read, update (via edit_note), and both title and full-text search, but notably lacks delete operations for notes or folders. This missing CRUD operation leaves users unable to remove items, creating a significant gap for a notes app.
Maintenance
Related MCP Connectors
An MCP server that used to create notes
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAn MCP server for Apple Notes that enables semantic search and full CRUD operations through natural language.38 npm7MIT
- 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
- AlicenseAqualityDmaintenanceAn MCP server for Apple Notes that can read and write checklist state, enabling agents to manage checklists in notes.15MIT