Apple Notes Skill

This skill enables you to manage Apple Notes on macOS through natural language. Use it whenever the user mentions notes, wants to save information to Notes, or needs to retrieve, update, or organize their notes.

When to Use This Skill

Use this skill when the user:

• Wants to create a new note or save information
• Asks to find, search, or look up notes
• Wants to read the contents of a note
• Needs to update or edit an existing note
• Wants to delete or remove a note
• Asks to move or organize notes into folders
• Wants to list their notes or folders
• Mentions Apple Notes, Notes app, or "my notes"

Available Tools

Note Operations

To edit a template visually, the user can run apple-notes-mcp templates edit [name] in a terminal: a local, token-gated web editor with live validation and a preview on sample notes. It is a command-line tool, not an MCP tool, so suggest it rather than trying to start it.

Folder Operations

Account Operations

Native Tags

Attachments, Checklists, Collaboration, and Diagnostics

Private Helper (opt-in, read-only, unsupported Apple API)

Off unless the user built it (apple-notes-mcp setup --native-helper) and set APPLE_NOTES_MCP_ENABLE_PRIVATE=1. Call native-helper-status first; use native-note-state or native-checklist-state only when the corresponding readNoteState or readChecklist feature is available. The helper is read-only: write support was deliberately deferred by the maintainer.

Usage Patterns

Creating Notes

When the user wants to save information:

User: "Save this meeting summary as a note"
Action: Use create-note with an appropriate title and the content

User: "Create a shopping list note"
Action: Use create-note with title="Shopping List" and formatted content

For structured notes, pass format="html" and use simple Apple Notes-friendly HTML. The server automatically prepends the title as an <h1> in both plaintext and HTML modes, so do not include the same <h1> title in content when creating a note.

Finding Notes

When the user wants to find notes:

User: "Find my notes about the project"
Action: Use search-notes with query="project"

User: "Search for notes containing budget information"
Action: Use search-notes with query="budget" and searchContent=true

With Full Disk Access, a searchContent search reads the Notes database and returns quickly even for a common word; without it, a broad body search can time out, so narrow it with folder or modifiedSince.

When Full Disk Access is available, prefer query-notes for anything beyond a single keyword. It matches title or body in one call, runs in well under a second, and combines conditions:

User: "Which work notes still have open to-dos?"
Action: Use query-notes with query='folder:Work checklist:open'

User: "Find invoices or anything tagged finance since July"
Action: Use query-notes with query='(title:invoice OR tag:finance) modified:>=2026-07-01'

User: "Long notes with a PDF that aren't in Archive"
Action: Use query-notes with query='words:>250 has:pdf -folder:Archive'

Bare words and "quoted phrases" match title or body. Fields are title:, body:, text:, folder:, account:, and tag:; facets are has:link|attachment|checklist|drawing|image|video|audio|pdf|table|scan|url|map|tag (has:url is a link preview card, has:map a map); checklist:open|done; flags pinned, locked, shared, quicknote; and words:, created:, modified: take =, >, >=, <, <= with YYYY-MM-DD local dates. AND is implicit; use OR, NOT or a leading -, and parentheses. Quote an operator word ("and") to search it literally. It scans the 500 most recently modified notes unless scanLimit is raised (max 10000), and the response says when older notes were left out. Recently Deleted is excluded unless includeDeleted is true. Locked notes match on title and metadata only. The returned ids work with every id-based tool.

Both search tools can say where a note matched and how long it is. Results whose text came from the database carry matchedIn (title, body, or both); query-notes always has it for readable notes, and search-notes has it for a database body search. Pass includeWordCount: true to either tool for a wordCount per result (null for locked notes). On a search-notes title search it reads the bodies in one database query and adds matchedIn too, which answers "does this note also mention it in the body?" without opening each note.

User: "Which of my budget notes are long, and do they mention it in the body?"
Action: Use query-notes with query='budget' and includeWordCount=true

Reading Notes

When the user wants to see note contents:

User: "Show me my shopping list"
Action: Search by title if needed, then use get-note-content with the exact ID

For a note's tables, use get-note-tables with the note ID. It returns a page of whole tables as Markdown and JSON rows. While page.hasMore is true, repeat with offset: page.nextOffset and the same limit and maxBytes. The full response defaults to 4 MiB (maximum 8 MiB) and 500 tables. An oversized table has contentOmitted: true, a reason and no rows; the next offset advances past it. Retry its original offset with a larger maxBytes or export the note to a file. When tableCellsComplete is false, check each entry's reason: undecodable cells are null in rows and shown as [undecoded cell] in Markdown. Report missing content rather than filling it in.

Use titles for discovery only. Mutations require the exact note ID; update, append, and delete also require the contentHash returned by get-note-content. This prevents duplicate-title mistakes and stale saves.

For a note with audio recordings, get-audio-transcripts returns the transcript Notes already computed for each recording (it never transcribes). Check each attachment's status: none means Notes stored no transcript, not that the read failed. Ask for includeSegments only when word timings or speakers per word matter, because segments make the response much larger.

Updating Notes

Adding to a note — use append-to-note. It takes the new content plus an optional position ("after" is the default and appends; "before" prepends), separator, and format ("plaintext" / "html"), and does the read-and-splice itself, always round-tripping the body as HTML so existing rich formatting survives. Do not hand-roll read-then-update-note for an addition.

A note that already contains native objects (a table, a checklist, native tags) cannot be spliced, so append-to-note routes it to the native end-append bridge instead. That path additionally needs scopeText (a unique existing phrase from below the title line; a title-only phrase is refused), keeps the default blank-line separator and position: "after", and accepts a fixed HTML subset: `<a> <b> <br> <code> <del> <div> <em> <h1> <h2> <h3> <i> <li>

Adding a web link — use insert-link. Pass url and either mode: "raw" (the URL is its own clickable text) or mode: "hyperlink" with a label. position is "end" (default) or "after-title". It checks the stored link afterwards and reports linkStored and storedUrl. A plain URL typed into append-to-note content stays plain text: Notes does not turn it into a stored link. Rich URL preview cards cannot be created. For a link to another note, use insert-note-link.

User: "Add milk to my shopping list"
Action:
1. Use search-notes if needed to get the note ID
2. Read it with get-note-content and retain contentHash
3. Use append-to-note with its exact ID, expectedContentHash, and content="Milk"

Replacing a note — use update-note. Only reach for it when the body really is being rewritten:

User: "Rewrite my project brief with this new version"
Action:
1. Use search-notes if needed to get the note ID
2. Read it with get-note-content and retain contentHash
3. Use update-note with its exact ID, expectedContentHash, and complete new body

update-note replaces the entire note body. It is not an append operation. If format="html", newTitle is ignored and the first element in newContent becomes the visible title, so start newContent with the title line (for example <h1>Project Brief</h1>). This is the opposite of create-note, which adds the title itself.

If the note has links, update-note needs format: "html", and every link get-note-content returned must still be in newContent with the same text and URL. A write that would drop or change one is refused. Pass allowLinkChanges: true only when the user asked to remove or change a link.

Do not write get-note-content's body back through another tool. For image-heavy notes that body is lossy: inline base64 images over the configured cap (default 256 KB each) come back as [inline image omitted: …] text placeholders.

update-note refuses a note whose body it cannot rewrite without loss: one that holds attachments, tables, checklists, or native tags, or uses formatting that Notes' AppleScript HTML does not carry (superscript, subscript, paragraph alignment, highlight). get-note-content reports that as writable: false with the reason. append-to-note does not refuse such a note. It switches to native end-append, which needs scopeText and the HTML subset above, and keeps the existing objects. Any other change to such a note belongs in Notes.app.

Organizing Notes

When the user wants to organize:

User: "Move my old notes to Archive"
Action: Search for each note, then use move-note with its exact ID and folder="Archive"

User: "Create a Work folder"
Action: Use create-folder with name="Work"

create-folder takes a whole nested path (name="Work/Clients/Omnia") and creates every missing segment, skipping ones that already exist — so it is idempotent and safe to call unconditionally. Do call it first: create-note, create-note-with-attachment, move-note, and batch-move-notes all require the destination folder to already exist (and never a smart folder: those destinations, and a smart folder anywhere in a create-folder path, are refused with reason: "smart_folder_destination", since Notes would send a moved note to Recently Deleted; the guard needs Full Disk Access to detect one), and create-note reports a missing folder with a generic "check that Notes.app is configured and accessible" message that looks like a permissions problem but is not.

Sharing and Revealing Notes

User: "Send me a link to that note"
Action: Use get-note-link with the note ID → notes://showNote?identifier=<uuid>

Hand out that deep link, not the x-coredata:// id — the link opens the note in Notes.app on macOS and iOS and can be pasted into a Reminders task or a message. It needs Full Disk Access for the process that runs the server (under Claude Desktop, the Node binary itself) (it reads the note's identifier from the Notes database; macOS 12–15 has an AppleScript fallback), and password-protected notes cannot be linked.

User: "Open that note for me" / "What note am I looking at?"
Action: show-note by ID to reveal it in Notes.app; get-selected-notes to read the current selection

show-note, show-folder, show-account, and show-attachment activate the Notes.app GUI, so they only do something useful on a Mac with an active desktop session.

Formatting Guidance

Use HTML for predictable rich notes. Apple Notes normalizes HTML internally, but these tags are reliable for most API-created content:

• Use <div> for body blocks and <div><br></div> for blank spacing.
• create-note already creates the top <h1> from the title, but <h2>/<h3> in its content do not produce real Heading/Subheading styles — AppleScript's body property renders them as plain bold text (#172). For a new note with real headings, use create-note with format: "markdown" (##/### → Heading/Subheading, flat lists, **bold**/*italic* and inline links; iCloud only, no account). tags are refused with this format: create the note, then use add-native-tags on the returned id. It needs the optional Create Markdown Note Shortcut (macOS 26+); check get-capabilities for create-note-markdown. On an existing note, use append-native with format: "markdown". Both refuse Markdown Notes would rewrite, such as _ emphasis outside a word or backslash escapes; underscores inside a link destination are fine.
• With format: "markdown", do not repeat the title as a # line; if the first line is exactly # <title>, the server removes it. Without the Shortcut, or in another account, pass markdownRoute: "html": same Markdown subset through AppleScript HTML, no real Heading styles, and - [ ] / - [x] task items become list rows with a visible ☐ / ☑ character (text, not a checkable checklist; say so to the user).
• To import a Markdown or text file, pass its absolute path as contentPath instead of content (UTF-8, at most 1 MiB, inside home, temp, or /Volumes; hidden paths such as ~/.ssh and anything in ~/Library are refused, except iCloud Drive and ~/Library/CloudStorage).
• On the default Shortcut route, create-note with format: "markdown" also maps block constructs to native Notes styles (create-note-markdown-blocks in get-capabilities): - [ ]/- [x] → native checklist items with that done state, > text → a block quote, a bare ``` fence (no language) → Monospaced paragraphs, a --- line after a blank line → a divider, and `inline code` → highlighted text (not monospace). Code content is kept literal. append-native still refuses all of these, because its converter flattens them (quotes and code to plain body text, - [ ] to a bullet with literal brackets, --- dropped). markdownRoute: "html" does not map them either: it renders - [ ]/- [x] as ☐ / ☑ glyph rows, keeps --- as literal text, and refuses the rest.
• Pass title as plain text. The server escapes &, <, and > in it, so an entity such as & in a title shows up literally.
• Use <ul><li> and <ol><li> for native bullet and numbered lists. Add <div><br></div> after closing </ul> or </ol> so the next section has spacing.
• Keep each <li> to one line of inline text. Do not put <div>, <p>, headings, or tables inside a list item, and do not send an empty <li>, which shows as a blank bullet or number. A <br> inside an item does not start a new line in Notes; the text after it joins the line. For sub-points, write the parent as its own <div> line and follow it with a separate flat list. HTML from a Markdown converter often wraps list items in <p>, so flatten it before sending. The server's own Markdown converter likewise emits only flat, one-line list items and refuses nested lists.
• Use <b>, <i>, <u>, and <s> for inline emphasis, and <span style="color: …"> for text color.
• Use <tt> (or <code>) for commands, code, paths, API keys, and other technical strings.
• Escape literal &, <, and > in user content as &, <, and >.
• Avoid nested lists when possible. Apple Notes can flatten or misplace nested list markup.
• Avoid <sup>, <sub>, and text-align in a note you may rewrite later. Notes applies them, but its AppleScript HTML does not return them, so the note becomes writable: false and update-note refuses it.
• <blockquote> does not create a Notes block quote. Use the Markdown route's > text instead (see below).
• For a table, use create-table on an existing note; it builds a native table and verifies its cells. A table is a native object, so afterwards update-note refuses the note and append-to-note switches to native append. Read tables back with get-note-tables.
• For a clickable link, use <a href="…"> in HTML content or insert-link. A bare URL written as text is stored as plain text, not as a link.
• Do not use decorative separators between sections (horizontal rules, repeated dashes, or box-drawing characters). They render inconsistently in Notes; use an empty <div><br></div> spacer instead.

Do not use CDATA sections. They can render literally in Apple Notes.

Attachment-Safe Updates

update-note refuses any note containing an attachment (a table counts, since Notes stores it as an embedded object). Do not bypass this control. To add text to such a note, use append-to-note with scopeText, which appends natively and leaves the attachments in place; to add a file, use add-attachment. For any other edit, use Notes.app or create a separate formatted note.

Formatting Limits

Some Notes UI features cannot be created through AppleScript HTML. Several have another route:

• Interactive checklists: in plaintext or HTML, create a plain list instead; create-note with format: "markdown" and - [ ]/- [x] lines creates real ones, and create-checklist-item / create-checklist-items append unchecked items to an existing note. Use get-checklist-state to read checklist state.
• Headings and collapsing: HTML <h2>/<h3> become bold text, not heading styles, so they get no collapse control. ##/### through create-note or append-native with format: "markdown" produce real Heading/Subheading styles.
• Block quotes and highlights: only the Markdown Shortcut route of create-note creates them (> text for a block quote, `inline code` for highlighted text, with no choice of color). Otherwise apply them in Notes.app.
• Dashed lists: no tool creates them; apply them in Notes.app.

If the user specifically requires those features, create all API-supported content first, then explain which remaining formatting must be applied in Notes.app.

Important Guidelines

1. Exact IDs for writes: Search may use titles, but update, append, delete, and move require the exact note ID. Update, append, and delete also require the contentHash from the version just read. A note ID may be the x-coredata://… id, the note's Notes UUID (the identifier field list and read tools return with Full Disk Access), or its numeric key (the digits after p). UUIDs and numeric keys need Full Disk Access; store the identifier when a reference must outlive this session.
2. Default Account: Operations default to iCloud. Use the account parameter for other accounts (Gmail, Exchange).
3. Content Format: Notes store content as HTML. Use format="html" for structured content. Retrieved HTML is normalized by Notes and may not match the submitted HTML byte-for-byte. verifiedVisibleText proves the words survived, not every rich-formatting detail.
4. Backslash Escaping: When content contains backslashes, escape them as \\ in the JSON.
5. Password-Protected Notes: Cannot be accessed via this skill. Inform the user if they try.
6. Shared Notes: Use extra care before edits or deletes. Changes to shared notes are visible to collaborators.
7. macOS Only: This skill only works on macOS systems.

Verification

get-note-content returns Apple Notes' stored HTML, which may differ from the original HTML while still rendering correctly. Use get-note-markdown, get-note-content, or a quick reread of the note after create/update to verify the title, line breaks, list spacing, and important content. Do not rewrite normalized HTML just because Notes transformed tags such as headings or monostyled text.

When the stored HTML looks suspicious, get-note-plaintext is the quickest check: it returns the note's plain-text body (what Notes itself shows) with no markup, so you can confirm the title, line breaks, and text survived without reading through normalized HTML.

Plain text cannot confirm structure. It carries no list markers, so it cannot show whether items became bullets or numbers, and a table's cell text is not part of it. With Full Disk Access, use get-note-blocks to check paragraph styles, list types, and indentation, and get-note-tables to check table cells. Stored HTML can also contain entities without a closing semicolon, such as &quot. That is how Notes writes them, not damage to repair.

Error Handling

Every error result carries structuredContent.code (not_found, ambiguous, permission_denied, full_disk_access_missing, shortcut_not_installed, timeout_indeterminate, verification_failed, revision_conflict, validation_error, unsupported, notes_unavailable, operation_failed). Branch on the code rather than the wording. If indeterminate is true, the write may have landed: read the exact note before deciding whether to retry. committed: false means nothing was written.

If your client shows only text, not structuredContent, every result that has it ends with a structuredContent: {…} line holding the same JSON. Take contentHash (for expectedContentHash), ids, and the error code from that line.

• "Note not found": Use search-notes to find similar titles
• "Permission denied": User needs to grant automation permission in System Settings > Privacy & Security > Automation. The user can run apple-notes-mcp setup --permissions --open --probe-automation in their terminal to check every grant and open each missing pane
• Native write times out or reports an uncertain outcome ("Shortcuts timed out waiting for …", "Operation outcome uncertain", "readback was not verified"): do not retry. Read the exact note first — the write may have landed. If it did not, the named bridge Shortcut is likely waiting on a first-run consent prompt that a background run cannot display; ask the user to run that Shortcut once in the foreground in Shortcuts.app and choose Always Allow (once per bridge, after install or upgrade), then retry
• Slow Notes.app: create-note, update-note, append-to-note, delete-note, and move-note accept timeoutSeconds (1–120) for each automation step of that call. A timed-out write is uncertain; read the exact note before retrying
• Read times out, or Notes.app cannot resolve an id the database holds: timeout_indeterminate and notes_unavailable from get-note-content mean Notes.app was busy (often iCloud sync), not that the note is gone; only not_found means that. Retry after a moment, or read the note with get-note-structure, which does not go through Notes.app
• Read times out on a note with a large image: Notes.app returns images inside the body as base64, so a multi-megabyte image can outlast the read timeout, which also blocks delete-note. The error names the large attachments when Full Disk Access is granted. Retry get-note-content (and then delete-note) with a larger timeoutSeconds; if it still fails, have the user remove the image or delete the note in Notes.app
• "Notes.app accepted the delete, but the note is still in its original folder": nothing was deleted. Read the note again before retrying
• "Notes.app returned more than … of output": a size limit, not a timeout, so retrying will not help. Note bodies embed inline images as base64; body reads accept up to 512 MB, and other calls follow APPLE_NOTES_MCP_MAX_BUFFER (64 MB default). A note with a large image can still be read and deleted by id
• "A note may have been created, but its exact ID could not be verified": do not call create-note again, or you may get a duplicate. The message carries the returned ID; read it, or search for the title, before deciding anything. After any create-note timeout, search for the title first for the same reason
• "The note accepted an update, but exact-ID readback visible text did not match": do not retry. Read the note and compare its text with what you sent
• "Folder not empty": Cannot delete folders with notes; move notes first
• Attachment-risk update: update-note rejects the mutation. Append with append-to-note and scopeText, use Notes.app, or create a separate note.
• Notes accumulate blank lines after repeated updates: Apple Notes' internal HTML processing preserves empty <div><br></div> artifacts from previous edits, and they persist even when you update with clean content. Fix: delete the note with delete-note and create a fresh one with create-note — the artifacts are baked into the note's internal representation, so this is more reliable than trying to fix the whitespace through updates

Examples

Save conversation to notes

User: "Save our conversation about the API design to my notes"
→ create-note with title="API Design Discussion" and summarized content

Daily workflow

User: "What's on my todo list?"
→ search-notes with query="todo" or get-note-content with title="Todo"

Multi-step organization

User: "Archive all my completed project notes"
→ 1. list-notes to find notes
→ 2. create-folder name="Archive" if needed
→ 3. move-note for each relevant note