Apple Notes

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