Skip to main content
Glama
applenotes-mcp
by iangray001

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_note falls back to AppleScript HTML, and edit_note will refuse to edit.

  • Automation → Notes (System Settings → Privacy & Security → Automation). Prompted for on the first osascript call.

Setup

uv sync

Register with Claude Code:

claude mcp add applenotes -- uv run --directory /path/to/applenotes_mcp applenotes-mcp

On 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.m

Generate 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.sqlite

Understand 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_note(title, markdown, folder?)

Create a formatted note, attachments and all. Returns its ID.

read_note(note_id)

Read a note back as markdown.

edit_note(note_id, markdown, title?)

Replace a note's body. Destructive — see below.

search_notes(query)

Find notes by title. Returns id<TAB>title<TAB>folder<TAB>modified<TAB>snippet.

search_note_text(query)

Full-text search over title and body. Same rows as search_notes.

list_folders()

The folders a note can be filed into, as full paths.

list_folder(folder)

Browse one folder: its notes (newest first) and immediate subfolders.

create_folder(path)

Create a folder, making any missing parents. create_note still refuses unknown folders.

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 ![pic|small](…) 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 pytest

This 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 live

Both live and APPLENOTES_MCP_LIVE must be set and both are checked before testing starts.

Licence

MIT — see LICENSE.

Available Tools

8 tools
create_folderA
Idempotent

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 ![alt](/path/to/file) 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 -- ![alt|small](...) -- 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_noteA
Destructive

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://...) / [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_folderA
Read-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_foldersA
Read-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_noteA
Read-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://...) / [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_notesA
Read-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_textA
Read-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

    A4.4/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers