Apple Notes MCP Server

A Model Context Protocol (MCP) server that lets Claude (Claude Code and Claude Desktop), Codex, and other MCP clients read, search, create, edit, organize, and export notes in Apple Notes on macOS. It runs locally on your Mac and talks to Notes through AppleScript, Apple Shortcuts, and read-only access to the Notes database.

Beyond creating and editing notes, it manages folders and accounts, native tags, checklists, tables, pinned notes, links, and attachments. It can also export notes as Markdown, HTML, or JSON, read audio transcripts and drawings, and run a query language across your whole library.

Contents

• What is This? · Quick Start · Requirements · Features
• Tool Reference: notes, folders, accounts, batch, export, attachments, and media, diagnostics, native background operations, private helper
• Usage Patterns · Installation Options · Configuration · Full Disk Access · Public native helper
• Security and Privacy · Known Limitations · Troubleshooting · Recurring macOS permission prompts · Development

What is This?

This server acts as a bridge between AI assistants and Apple Notes. Once configured, you can ask Claude (or any MCP-compatible AI) to:

• "Save this conversation as a note called 'Meeting Summary'"
• "Find all my notes about the project deadline"
• "Read my shopping list note"
• "Move my draft notes to the Archive folder"
• "What notes do I have in my Work folder?"

The AI assistant communicates with this server, which then uses AppleScript to interact with the Notes app on your Mac. Some features also use packaged Apple Shortcuts (native tags, checklists, tables, pinning) or read the Notes database read-only (queries, checklist state, transcripts). The server itself makes no network requests; what your MCP client does with the results is up to that client.

Quick Start

Using Claude Code (Easiest)

If you're using Claude Code (in Terminal or VS Code), just ask Claude to install it:

Install the sweetrb/apple-notes-mcp MCP server so you can help me manage my Apple Notes

Claude will handle the installation and configuration automatically.

Or register it yourself with one deterministic command:

claude mcp add apple-notes -s user -- npx -y apple-notes-mcp

Using the Plugin Marketplace

Install as a Claude Code plugin for automatic configuration and enhanced AI behavior:

/plugin marketplace add sweetrb/apple-notes-mcp
/plugin install apple-notes

This method also installs a skill that teaches Claude when and how to use Apple Notes effectively.

On the first tool call, macOS shows an Automation permission prompt ("Claude" wants access to control "Notes") — click OK. Optionally, grant Full Disk Access (under Claude Desktop, to the Node binary that runs the server; from a terminal, to the terminal app) to enable the database-backed tools, such as query-notes, get-checklist-state, get-note-tables, get-audio-transcripts, list-native-tags, and list-recent-notes (the full list is under Full Disk Access); see the Full Disk Access Setup Guide. The rest of the server is pure AppleScript and works without it.

Native tag, checklist, table, pin, and rich append operations use two packaged Apple Shortcuts. A third, Apple Notes MCP - Create Markdown Note, is optional: only create-note's format: "markdown" needs it, and only on macOS 26 or later. Run the explicit setup once:

npx -y apple-notes-mcp setup

The command checks existing installations and opens only missing signed workflows; it opens the optional Create Markdown Note bridge only on macOS 26 or later. Confirm Add Shortcut in each macOS window, then verify with npx -y apple-notes-mcp setup --check or the MCP doctor tool. setup --check reports ready and doctor reports ok once the two required bridges are installed; both list the optional bridge's status separately. macOS does not support silent Shortcut import, so merely connecting an MCP client never opens setup windows or bypasses these confirmations.

After install and after every upgrade, open Shortcuts.app and run each installed bridge — Apple Notes MCP - Native Tags, Apple Notes MCP - Background Operations v5 and, if you installed it, the optional Apple Notes MCP - Create Markdown Note — once in the foreground, choosing Always Allow when Shortcuts asks for permission. The Create Markdown Note bridge stops before reaching Notes when run with no input, so start its run with the request in shortcuts/README.md. The server runs these Shortcuts in the background, where Shortcuts cannot display a first-run consent prompt: an unanswered one stalls every native write on that bridge until it times out, while doctor still reports the bridge installed. Quitting or relaunching Shortcuts.app or Notes.app does not clear it; the foreground run does, once per bridge.

Using the Codex Marketplace

The same plugin is available for Codex. Add the marketplace and install the plugin:

codex plugin marketplace add sweetrb/apple-notes-mcp
codex plugin add apple-notes@apple-notes-mcp

The Codex plugin runs the published apple-notes-mcp server through npx and ships the same Apple Notes skill, so behavior matches the Claude Code plugin.

Other Hosts (Hermes, Antigravity)

Two more hosts can run the same apple-notes MCP server (npx -y apple-notes-mcp):

• Hermes Agent (NousResearch) — Hermes has no plugin/marketplace drop-in, so there is nothing in this repo to install from. Register the server with the CLI:

  hermes mcp add apple-notes --command npx --args -y apple-notes-mcp
  

  Or add it to ~/.hermes/config.yaml by hand:

  mcp_servers:
    apple-notes:
      command: npx
      args: ["-y", "apple-notes-mcp"]
  

  Restart your Hermes session afterward so the tools load.

• Antigravity (Google) — add the server entry from .antigravity-plugin/mcp_config.json to ~/.gemini/config/mcp_config.json (or via Antigravity's MCP settings).

Using Claude Desktop

1. Install the server:

npm install -g apple-notes-mcp

2. Add to Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "apple-notes-mcp"]
    }
  }
}

3. Restart Claude Desktop and start using natural language:

"Create a note called 'Ideas' with my brainstorming thoughts"

On first use, macOS will ask for permission to automate Notes.app. Click "OK" to allow.

Other MCP clients

The server is a standard MCP server over stdio, so any client that can launch a local stdio server can run it with the same command the hosts above use: npx -y apple-notes-mcp. Most clients take it in an mcpServers entry shaped like the Claude Desktop example. If your client cannot pass environment variables, use the configuration file.

Requirements

• macOS - Apple Notes and AppleScript are macOS-only
• Node.js 20+ - Required for the MCP server
• Apple Notes - Must have at least one account configured (iCloud, Gmail, etc.)

Features

Read/list/get tools also return structured JSON (structuredContent) alongside the text, so agents can consume results without parsing prose.

Some clients (Claude Desktop among them) pass the model only a result's text and drop structuredContent. So every result that has structuredContent also ends with one more text block holding the same data as a single JSON line:

structuredContent: {"id":"x-coredata://…/ICNote/p123","contentHash":"sha256:…","writable":true,…}

That line carries every token a follow-up call needs: the contentHash revision token for expectedContentHash, new ids, nativeTags, writable, page.nextOffset, and an error's code, committed and indeterminate. A long value the text above already shows in full, such as the body from get-note-content, appears as "[shown in full above]" instead of twice. If the line would still exceed 16 KB, fields larger than 1 KB (usually a list already printed above) are left out and named in _omitted. Tools whose text already is that JSON get no extra block. structuredContent itself is unchanged.

MCP resources & prompts

Resources expose read-only context the client can attach without a tool call: notes://accounts, notes://folders, notes://stats, and the notes://note/{id} template (returns the note as Markdown). Prompts package common workflows: find-note, weekly-review, new-meeting-note.

AppleScript limitations

A few Notes UI features are not exposed to AppleScript. Some are recovered by reading Notes' own database instead; the rest genuinely cannot be supported. See docs/APPLESCRIPT-LIMITATIONS.md for the investigation and verification behind each:

• Pinned notes — Notes has no scriptable pinned property via AppleScript. Pin state is read from the NoteStore database by the BETA get-note-metadata tool and list-special-notes, and set through the Background Operations Shortcut by set-note-pinned.
• Note-to-note links — AppleScript exposes no link property or link element. Links are instead read from the NoteStore database by list-note-links, and inserted by insert-note-link (through a Shortcut) or insert-link. A shareable notes://showNote?identifier=<uuid> deep link is available via get-note-link.

Tool Reference

This section documents all available tools. AI agents should use these tool names and parameters exactly as specified.

Identifier forms

Every tool that takes a note id (id, noteId, ids, linkedNoteId, or the id inside a batch entry) accepts any of three forms of the same note:

The server turns a UUID or numeric key into the canonical id before the tool runs, reading the Notes database read-only. A numeric key or UUID resolves only to a note, never to a folder or attachment. Without Full Disk Access those two forms fail with an error that says so, while x-coredata ids keep working as before. Folder-id inputs (show-folder, get-folder-by-id, rename-folder) accept a folder's UUID or numeric key the same way, resolving only to folders.

When Full Disk Access is granted, list and read tools also return stable identifiers next to each id: notes carry identifier, folderIdentifier, and accountIdentifier; folders carry identifier, parentIdentifier (nested folders only), and accountIdentifier; accounts carry identifier. These fields come from one batched read-only query per call and are omitted when the database cannot be read. Tools that return them: search-notes, list-notes, get-selected-notes, list-shared-notes, get-note-content, get-note-by-id, get-note-details, list-folders, get-folder-by-id, list-accounts, and get-default-location.

Error results

A failed call returns isError: true with the same human-readable text as before, plus structuredContent carrying a stable machine-readable code (also repeated in the trailing structuredContent: text line, for clients that drop structuredContent). Branch on code, not on the prose, which may be reworded.

Two optional booleans describe a write's outcome when it is known. indeterminate: true means the outcome is uncertain: read the target by exact id before any retry, and never retry blindly. committed: true means the write took effect even though its verification failed; committed: false means nothing was written (for example a revision_conflict). An absent flag means unknown. An argument that fails the input schema is rejected before the tool runs, with code: "validation_error" and committed: false. The exception is a Notes UUID or numeric key that could not be resolved to an id: it carries not_found, or full_disk_access_missing when the database is unreadable.

Note Operations

create-note

Creates a new note in Apple Notes.

Example (with inline textual hashtags):

{
  "title": "Meeting Notes",
  "content": "Discussed Q4 roadmap and budget allocation\n\n#work #meetings"
}

Example - Create in a specific folder:

{
  "title": "Client Meeting",
  "content": "Discussed project timeline",
  "folder": "Work/Clients"
}

Example - HTML formatting:

{
  "title": "Status Report",
  "content": "<h2>Summary</h2><p>All tasks <b>on track</b>.</p><ul><li>Feature A: complete</li><li>Feature B: in progress</li></ul>",
  "format": "html"
}

Note: The title is automatically prepended as <h1> in both plaintext and HTML formats. Do not include a <h1> title tag in the content parameter, or the title will appear twice.

Known limitation: with "plaintext" or "html", create-note sets the note body directly via AppleScript's body property, which does not apply real Notes paragraph styles for interior content — an <h2>/<h3> tag or a <span style="font-size: …px"> heading span in content renders as plain bold, styled text, not an actual Heading or Subheading (#172). Use format: "markdown" for real headings in a new note, or append-native's format: "markdown" on a note that already exists.

Markdown notes

format: "markdown" creates the note with Notes' own Markdown importer (the Create Note action's "Interpret as Markdown" option, macOS 26+), run through the packaged Apple Notes MCP - Create Markdown Note Shortcut. #, ## and ### become real Title, Heading and Subheading styles, and the note starts with the title line, with no seed line.

{
  "title": "Project Plan",
  "content": "## Goals\n\n- Ship the beta\n- Collect feedback\n\n### Links\n\n[Tracker](https://example.com/tracker)",
  "format": "markdown",
  "folder": "Work"
}

• Notes interprets Markdown only in an iCloud account. The note is created in the iCloud account's default folder, then moved to folder in that account. folder must already exist and is checked before anything is created. If it exists only in another account, the note is still created and verified in the iCloud default folder, and the error names that account and the note's id so you can create the folder there and move-note it instead of creating the note again. account is refused with this format.

• tags are refused with this format. Create the note without them, then add native tags to the returned id with add-native-tags.

• content accepts the same bounded subset as append-native's Markdown: #/##/### headings, flat lists, **bold**, *italic* and inline links. It also refuses Markdown that Notes would rewrite and the server could not verify: _ emphasis (underscores inside a word, as in snake_case, and inside a link destination, as in [docs](https://example.com/_next/static), are fine), backslash escapes, character references such as &, === lines and rule lines other than the --- divider described below, indented headings or list items, 1) lists, closing #s, and formatting inside link labels. Content that needs one of these literally, such as a /_next path or a literal \*, has no Markdown form here: use format: "html" for that note (or append-native with format: "html" on an existing one), which keeps the characters but not the Heading and Subheading styles. Markdown punctuation in title is escaped, so the title stays literal.

• Notes' importer also maps these block constructs to native styles. They are gated separately, and get-capabilities reports them as create-note-markdown-blocks. Each mapping below was live-verified on macOS 27.2 by reading the created note's stored styles.

  Markdown	Native result
  - [ ] item / - [x] item	Checklist item, unchecked / checked
  > text (consecutive lines form one quote)	Body paragraph with a block quote
  A fence of bare ``` lines (no language)	Monospaced paragraphs; the code text is kept literally
  --- on its own line, after a blank line	Divider line
  `inline code`	Highlighted text, not monospace

  Constructs Notes would not render faithfully, or that this server cannot yet verify, are refused before anything is created: ~~~ fences, a language after the opening fence, nested (>>) or indented quotes, lists or headings inside a quote, a quote followed directly by text (Markdown would join that text to the quote), --- directly under text (Markdown would make that text a heading), ***/___/---- rules, [X], * [ ] or + [ ] items, checklist items directly next to ordinary list items, inline code padded with spaces or inside a link label, tables, and ~~strikethrough~~. The readback checks the block-quote text, the Monospaced text, each checklist item's text and done state, the divider count, and the highlighted text. These mappings apply to the default Shortcut route only; see Markdown through HTML for markdownRoute: "html".

• append-native's format: "markdown" refuses all of the constructs above: its Shortcuts converter is a different one, which renders a quote and a fenced block as plain body text, - [ ] as a bullet with literal brackets, and inline code as plain text, and drops ---.

• The server finds the new note among the notes added to the default folder during the run by verifying each one's visible text, heading levels and links by exact-ID readback, and moves it only after exactly one verifies. On any uncertain result it names the note (or says to search for the title) and never retries.

• It is gated like the other native operations; get-capabilities reports it as create-note-markdown. The Create Markdown Note Shortcut is optional and needed only for this format (macOS 26+); install and approve it as described in shortcuts/README.md.

• A first line that is exactly # <title> (same case and spacing as title) is removed together with one blank line after it, because the title is supplied separately; the response then carries strippedDuplicateTitle: true. A different first heading stays in the body. This applies to both Markdown routes, and Markdown that holds only that heading is refused.

Markdown through HTML

markdownRoute: "html" imports the same bounded Markdown subset without the Shortcut: the server converts it to HTML and creates the note through AppleScript, like format: "html". It works in any account, accepts tags, and needs no Shortcut, but headings get the plain bold styling described in the known limitation above rather than real Heading and Subheading styles.

On this route, bullet task items (- [ ] item, - [x] item) become ordinary list rows that start with a visible ☐ or ☑ character, and the response reports how many as taskItemsRendered. They are text, not native checkable checklist items. Use this route as the glyph fallback when the Shortcut is not installed or the note is outside iCloud. Block quotes, fenced code and inline code, which the Shortcut route maps natively, are refused on this route, and a --- line stays literal text rather than becoming a divider.

{
  "title": "Weekly Review",
  "contentPath": "/Users/me/Documents/weekly-review.md",
  "format": "markdown",
  "markdownRoute": "html",
  "folder": "Work"
}

Returns: Confirmation message with note title and ID. Save the ID for subsequent operations like update-note, delete-note, etc.

search-notes

Searches for notes by title or content.

Example - Search titles:

{
  "query": "meeting"
}

Example - Search content:

{
  "query": "budget allocation",
  "searchContent": true
}

Example - Search recent notes with limit:

{
  "query": "todo",
  "searchContent": true,
  "modifiedSince": "2025-01-01",
  "limit": 10
}

Returns: List of matching notes with titles, folder names, and IDs. Use the returned ID for subsequent operations like get-note-content, update-note, etc. A content search also returns source ("database" or "applescript"), and scanTruncated when the database path left older notes unsearched.

When the note text came from the database (a database content search, or any search with includeWordCount), each result also carries matchedIn: ["title"], ["body"], or ["title", "body"], saying where the query text occurs. The body is the text after the first line. matchedIn is absent for locked notes and for AppleScript searches without includeWordCount. The text output appends the same details to each line, for example · matched in title, body · 245 words.

Example - Content search with word counts:

{
  "query": "budget",
  "searchContent": true,
  "includeWordCount": true
}

query-notes

Finds notes with a boolean query expression evaluated against the NoteStore database, read-only. Because it does not go through AppleScript, a query over several hundred notes typically returns in well under a second, and one call can match titles and bodies together.

Requires: Full Disk Access for the MCP host process (see Full Disk Access Setup). Without it, use search-notes.

Syntax:

Operators are case-insensitive. Quote an operator or flag word to search it literally, for example "and" or "pinned". Queries are capped at 256 tokens and 64 levels of nesting. An unknown field such as titel:x is an error rather than a silent text search; quote it to search the literal text.

Password-protected notes match on title and metadata only. Their bodies are encrypted, so a body predicate is unknown for them rather than false: neither body:x nor -body:x matches them, though -body:x OR pinned matches a pinned one. Notes whose body cannot be decoded are treated the same way. Their snippets are always empty.

Example - Open to-dos in a folder:

{
  "query": "folder:\"Work Projects\" has:checklist -checklist:done"
}

Example - Invoices or finance-tagged notes since July, scanning more history:

{
  "query": "(title:invoice OR tag:finance) modified:>=2026-07-01",
  "scanLimit": 2000,
  "limit": 20
}

Returns: Matching notes, most recently modified first, each with id, title, folder, account, modified, created, and a snippet centred on the first matched phrase. Each note also has matchedIn when the query has a positive text term: ["title"], ["body"], or both, saying where those terms occur (a title: term is only looked for in the title, a body: term only in the body). It is absent for locked or undecodable notes, and an empty list means the note matched through a non-text branch such as pinned OR x. The ids are the same x-coredata://…/ICNote/p… form every other tool accepts. structuredContent also reports matched (total matches), scanned, eligible, scanTruncated, truncated, and unreadable (bodies that could not be decoded). A malformed query returns an error naming the problem and its position.

get-note-content

Retrieves the full content of a specific note.

Note: Either id or title must be provided. Using id is recommended as it's unique and avoids issues with duplicate titles.

Large images: Notes.app returns images inside the body as base64, so a note holding a very large image (tens of MB) can take longer to read than the timeout allows. When the read times out or overflows the output buffer, the error says so and, with Full Disk Access, names the attachments of 5 MB or more. Retry with a larger timeoutSeconds; delete-note accepts the same argument, and it needs a successful read to verify the note before deleting it.

Example - Using ID (recommended):

{
  "id": "x-coredata://ABC123/ICNote/p456"
}

Example - Using title:

{
  "title": "Shopping List"
}

Returns: The HTML content of the note, its exact id, and a contentHash. Pass that hash back as expectedContentHash for a later update, append, or delete; the write is rejected if the note's body or rich metadata changed after this read. With Full Disk Access, embedded URLs omitted by AppleScript are restored and returned in links. The response also reports actual nativeTags, richContentComplete, and writable. Textual hashtags remain a separate field and are not proof that Notes registered native tags. writable is also false when the note uses formatting that AppleScript's HTML does not carry (superscript, subscript, non-left paragraph alignment, or highlight): a full-body update-note would silently drop it, so it is refused and the warning names the formatting. append-to-note with scopeText still works through the native path, which verifies existing formatting.

⚠️ The returned body can be lossy — do not write it back verbatim. Inline base64 images larger than APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES (default 256 KB) are replaced with [inline image omitted: …] text placeholders so an image-heavy note cannot blow the MCP message limit. structuredContent reports this as strippedImages (count) and truncated (boolean). When either is set, passing this body to an unguarded full-body writer would replace the real images with placeholder text. This server's update-note refuses attachment-bearing notes, and append-to-note routes them to native end-append with scopeText, which never rewrites the existing body; make any other edit in Notes.app.

get-native-objects

Reads native object identities and ranges, checklist item IDs and state, actual native tags, and native table data from one exact note ID. Table output includes stable row and column identifiers. tableCellsComplete is false when Notes metadata cannot be decoded completely. This tool is read-only and requires Full Disk Access.

get-note-tables

Reads every native table in one exact note, in body order, from the NoteStore database. Each table is returned as GitHub-flavored Markdown and as JSON rows with stable rowIds and columnIds. Notes tables have no header row, so the Markdown uses the first row as the header. Pipes are escaped as \|, backslashes are doubled, and line breaks inside a cell become <br>.

tableCellsComplete is false when any table or cell could not be decoded. A cell holding an embedded object is null in rows, listed in incompleteCells, and shown as [undecoded cell] in Markdown. A table whose data cannot be decoded at all has complete: false, a reason, and no rows. Cell text is never guessed. Links and styling inside cells are not rendered. A note without tables returns an empty tables list. This tool is read-only, requires Full Disk Access, and refuses password-protected notes.

get-note-blocks

Decodes one note's body into typed blocks, read-only, from the NoteStore database. Each block is one paragraph with its style (title, heading, subheading, body, monospaced, bulleted, dashed, numbered, checklist, or unknown with the raw styleType), indent, alignment, blockQuote, checklist id/done, and paragraphUuid when stored. Each block lists its inline runs with bold, italic, underline, strikethrough, superscript, subscript, color, highlight, link (plus linkSafe), font, and attachment, and its attachment markers in body order. Offsets and lengths count UTF-16 code units. summary counts styles and inline attributes for the whole note. undecodedFields lists stored field numbers the decoder deliberately does not interpret.

Requires: Full Disk Access. Password-protected notes are refused.

A page also stops early to stay under APPLE_NOTES_MCP_BLOCKS_MAX_BYTES (default 4 MB). paragraphUuid is not unique: Notes copies it when a paragraph is split. Link URLs are returned as stored, and linkSafe is false for schemes other than http(s), notes:, applenotes: and mailto:. Errors carry a stable code in brackets, such as [encrypted] or [no-full-disk-access].

list-note-paragraphs

Lists one note's non-empty paragraphs in body order, read-only from the NoteStore database. Each paragraph has blockIndex (its index in get-note-blocks, where empty paragraphs also count), text, style, styleType, paragraphId (the UUID Notes stores on the paragraph's first text run), and paragraphIdStatus:

• unique: no other paragraph in the note carries this ID. The paragraph also gets url, a direct applenotes://showNote?identifier=<note>&paragraphID=<paragraph> link that opens Notes at that paragraph.
• shared: other paragraphs carry the same ID (sharedWith counts them). Notes copies the ID when a paragraph is split, so this is common for body text. No url is given, because it could open the wrong paragraph.
• missing: no ID is stored.

mixedParagraphIds: true marks a paragraph whose text runs carry more than one ID; only the first-run ID is used. Titles and headings usually have unique IDs.

Requires: Full Disk Access. Password-protected notes are refused.

get-paragraph-link

Returns a direct link to one paragraph of a note: applenotes://showNote?identifier=<note>&paragraphID=<paragraph>. It selects the note like list-note-paragraphs and the paragraph by exactly one of:

• contains: a snippet of the paragraph. Case, runs of spaces, and Unicode width are ignored.
• match: the whole paragraph, compared the same way.
• blockIndex: from list-note-paragraphs.

When contains or match hits several paragraphs, pass occurrence (1-based) or a longer snippet.

The link is returned only when the paragraph's ID is unique in the note. Otherwise the result is an error whose structuredContent carries the usual code plus a reason: paragraph-id-shared, paragraph-id-missing, no-match, ambiguous-paragraph, occurrence-out-of-range, ambiguous-note (several notes have that title; the message lists their folders), not-found, encrypted, or no-body. The tool never creates or changes a paragraph ID, and an edit in Notes can later replace the ID and break the link.

Requires: Full Disk Access.

get-note-structure

Returns a read-only overview of one note from the NoteStore database, in one call:

• text (decoded body), textLength, wordCount, charCount (Unicode characters, attachment placeholders excluded), and blockSummary (the get-note-blocks summary counts).
• links, each with a kind: inline (a hyperlink on text), card (a rich link preview attachment, with attachmentId and previewPath), note (a native link chip to another note), or section (a native link chip to a heading or paragraph, with section). Notes deep links also carry targetNote and paragraphId. linkCounts totals them.
• tags (native tags in body order) and attachments, listed the way list-attachments with includePaths lists them: the same kind (image, scan, drawing, pdf, audio, video, url, table, other), the same body order, and the same previewPath, plus the card title/url, fileSize, and body position. Gallery items and recording parts are nested under children; attachmentCount counts top-level attachments only.
• deepLink, isShared (the note or any enclosing folder is shared), isLocked, isPinned, inRecentlyDeleted, lastViewed, checklistTotal, checklistDone, hasDrawing (classic sketches and Paper drawings), and firstImage (the same lead visual list-attachments returns with firstImage, plus its attachment id).

lastViewed is an ISO date, or null with lastViewedStatus set to never-viewed, not-recorded, malformed, or unsupported (the column does not exist on this macOS version). A password-protected note returns its metadata and attachment rows with bodyDecoded: false and the body-derived fields null.

Requires: Full Disk Access.

Link URLs are returned as stored; check linkSafe before emitting one into HTML.

list-note-links

Lists links, read-only from the NoteStore database, in one note (id) or across a folder, an account, or the whole library (no selector). Each link has a kind:

Each row has url, text (label), linkSafe, targetNote and paragraphId for Notes deep links, section for section chips, and for cards attachmentId and previewPath (Notes' largest cached preview image, found the same way list-attachments finds it, or null when Notes has none). Each row also names its source: noteId, noteIdentifier, noteTitle, noteModified, folder, folderPath (as list-folders prints it), account, and accountIdentifier. When bodies were decoded, start and blockIndex give the link's position, and inBody: false marks a card or chip row with no marker left in the body.

Inline links need every body in scope decompressed and decoded, so a folder, account, or library scan includes them only with includeInline: true (slower). A single note always includes them. A folder scope includes its subfolders unless includeSubfolders is false. Scans skip Recently Deleted and folderless notes; a note requested by id is read wherever it is. Links come newest-modified note first, in body order within a note.

Requires: Full Disk Access.

The response also reports scope, counts per kind, notesInScope, notesWithoutBody (locked, empty or undecodable bodies when inline links were requested), and page. A page stops early to stay under APPLE_NOTES_MCP_BLOCKS_MAX_BYTES. An ambiguous folder name is refused with a message that lists the matching paths.

list-native-tags

Lists actual native Notes tags. This differs from textual hashtag search. It is read-only and requires Full Disk Access.

• Folder mode (pass folder, optionally account): maps each tag used in that folder to its matching note IDs. The response reports complete: false and per-note errors when some native metadata is unavailable.
• Inventory mode (omit folder): an account-wide inventory with counts, read-only from the database. account narrows it to one account; omit it to count every account. Each inventory entry has tag, noteCount (distinct notes, Recently Deleted excluded), per-account counts in accounts, and any other spellings Notes treats as the same tag. Tags with no remaining notes are listed with noteCount: 0. A tag counts for a note only while the note body still references it. Locked or unreadable bodies are counted from the tag objects alone and reported through unverifiedNotes and complete: false.

native-tags-status

Checks whether exactly one configured Native Tags Shortcut is installed. An installed workflow may still need macOS permission on its first execution, and installation does not show whether that consent was given: run it once in the foreground in Shortcuts.app and choose Always Allow after install or upgrade (see Troubleshooting).

add-native-tags

Adds actual native Notes tag objects to one exact note using id, a fresh expectedContentHash, a distinctive existing scopeText, and tags. The operation verifies the note's original text, links, and native objects after the Shortcut runs. It refuses ambiguous title-and-scope matches and never retries an uncertain write. Install the signed workflow as described in shortcuts/README.md.

get-note-plaintext

Retrieves a note's body as plain text, with no HTML markup.

Note: Either id or title must be provided. This reads the note's native plaintext property, so it skips the HTML-to-text conversion that get-note-content plus a Markdown pass would do. Use get-note-content when you need the HTML, or get-note-markdown when you want Markdown with checklist state.

Returns: The plain-text content of the note in structuredContent.plaintext, or error if not found.

get-note-details

Retrieves metadata about a note (without full content).

Example:

{
  "title": "Project Plan"
}

Returns: JSON with note metadata:

{
  "id": "x-coredata://...",
  "title": "Project Plan",
  "created": "2025-01-15T10:30:00.000Z",
  "modified": "2025-01-20T14:22:00.000Z",
  "shared": false,
  "passwordProtected": false,
  "account": "iCloud"
}

get-note-by-id

Retrieves a note using its unique CoreData identifier.

Returns: JSON with note metadata, plus identifier, folderIdentifier, and accountIdentifier when Full Disk Access is granted, or error if not found.

show-note

Reveals a note in Notes.app using its unique CoreData identifier.

Returns: Confirmation that Notes.app accepted the show command.

update-note

Updates an existing note's content and/or title.

Title-only updates are rejected because Apple Notes titles are not unique.

Example - Using ID (recommended):

{
  "id": "x-coredata://ABC123/ICNote/p456",
  "expectedContentHash": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "newContent": "Updated content here"
}

Example - Update with HTML formatting:

{
  "id": "x-coredata://ABC123/ICNote/p456",
  "expectedContentHash": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "newContent": "<p>New findings with <b>bold</b> emphasis.</p><pre><code>console.log('hello');</code></pre>",
  "format": "html"
}

Returns: Confirmation with the exact ID, post-save contentHash, and verifiedVisibleText: true, or an error if the note changed before saving. Apple Notes normalizes HTML, so this proves the visible text after saving, not byte-identical rich formatting.

Note: newContent replaces the entire note body — it is not appended. To add to a note, prefer append-to-note, which does the read-and-concatenate for you and always round-trips the body as HTML. If you do read-modify-write by hand, note that get-note-content replaces oversized inline images with text placeholders (see get-note-content) — writing that body back bakes the placeholders in.

Rich-content safety: update-note refuses to replace a note when its rich metadata is unavailable or it contains attachments, native tags, inline objects, or checklists that AppleScript cannot preserve. Existing link destinations must remain present unless allowLinkChanges is explicitly set.

delete-note

Deletes a note (moves to Recently Deleted in Notes.app).

Title-only deletion is rejected. If the note changed after the supplied hash was read, deletion is also rejected.

Notes with large images. Notes.app returns a note's body with each inline image embedded as base64, so a note holding one 40 MB image has a body of about 110 MB. Body reads accept up to 512 MB of output, and delete-note compares a body longer than 5 MB against a private temporary file rather than embedding it in the AppleScript. The comparison still covers the whole body, and the file is removed when the delete finishes.

Copy-then-retire. To delete an original only while its copy is still good, read both notes, verify the copy, and pass the copy as guardNoteId with its contentHash as expectedGuardContentHash. The copy's revision is re-read just before the delete, and its body, lock state, and folder are checked again inside the delete AppleScript, with the same fail-closed Recently Deleted test as the note being deleted. The guard note must not be a Quick Note, a flag only the database holds, so the guard needs Full Disk Access. A copy the database has not saved yet passes on the live checks alone. The pair is still not one transaction: the rich revision (which also covers checklists and attachments) is a pre-check, and the in-script check covers the body and state Notes.app exposes. requireActiveNoteId is the narrower form for a destination you wrote yourself rather than copied.

Example - Using ID (recommended):

{
  "id": "x-coredata://ABC123/ICNote/p456",
  "expectedContentHash": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

Returns: Confirmation message, or error if note not found. The delete and a check of the note's original folder run in one AppleScript: if Notes.app accepts the delete but the note is still listed in that folder, the call reports that nothing was deleted instead of claiming success.

A note that is already in Recently Deleted is refused, because deleting it there removes it permanently. The folder is read live from Notes.app in the same AppleScript; the Recently Deleted folder is recognised by its database id (with Full Disk Access) or by its English name. The check fails closed: a note whose folder Notes.app reports as something other than a folder (as it does for a note trashed earlier in the same Notes session) is refused the same way, and a note whose folder cannot be read at all is refused with a message to retry. To remove such a note for good, do it in Notes.app.

⚠️ Safety: Irreversible from the agent's side — requires explicit user confirmation before calling. Prefer search-notes / list-notes first to confirm the exact id(s) being deleted.

move-note

Moves a note to a different folder. The note is relocated in place via Notes.app's native move, so its id, creation date, and all embedded attachments (files, images, scans, PDFs, audio) are preserved. The destination folder must already exist — create it first with create-folder.

A smart folder is never a destination: it only gathers notes by its rules, and Notes.app would move the note to Recently Deleted or store a created note where no folder shows it. create-note, create-note-with-attachment, move-note, batch-move-notes, and create-folder refuse one before writing anything, with code: "unsupported", committed: false, and reason: "smart_folder_destination". An ordinary folder that shares a smart folder's name is still found. Detection reads the NoteStore database, so it needs Full Disk Access; without it, destinations resolve as before.

Title-only moves are rejected.

Example - Using ID (recommended):

{
  "id": "x-coredata://ABC123/ICNote/p456",
  "folder": "Archive"
}

Returns: Confirmation only after the same note ID is read back and its actual destination folder ID matches the requested folder.

Folder scope guards

update-note, append-to-note, delete-note, and move-note accept three optional folder preconditions. Use exact folder ids from list-folders.

• ifFolderId: the note must currently be in exactly this folder.
• ifAncestorFolderId: the note must be inside this folder or any of its subfolders.
• forbiddenAncestorFolderIds (up to 50): the note must not be inside any of these folders or their subfolders. For move-note, the destination must not be either.

The checks read Notes.app's live folders inside the same AppleScript as the write, immediately before it, so a note moved after you reviewed it is left alone and the call fails with Scope guard failed: …. The one exception is a native append to a protected note (it runs through Shortcuts): there the check is a separate read just before the append, so it is not atomic.

Example - retire a note only while it is still in the inbox:

{
  "id": "x-coredata://ABC123/ICNote/p456",
  "expectedContentHash": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "ifFolderId": "x-coredata://ABC123/ICFolder/p12"
}

append-to-note

Appends or prepends content to an existing note without replacing it. Always reads and writes as HTML, preserving all existing rich formatting.

Title-only appends are rejected.

Example - Append plaintext:

{
  "id": "x-coredata://ABC123/ICNote/p456",
  "expectedContentHash": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "content": "New item added today"
}

Example - Prepend HTML:

{
  "id": "x-coredata://ABC123/ICNote/p456",
  "expectedContentHash": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "content": "<div><b>Status:</b> done</div>",
  "format": "html",
  "position": "before"
}

Returns: Confirmation with the exact ID, post-save contentHash, and verifiedVisibleText: true. Apple Notes normalizes HTML, so this proves the visible text after saving, not byte-identical rich formatting. Warns when the note is shared with collaborators.

Safety: The append is rejected if the note changed since it was read, rich metadata is unavailable, or the note contains attachments. Existing link destinations are verified after saving.

Notes containing native objects (a table, a checklist, native tags) cannot be spliced, so they are routed to the native end-append bridge — see append-native. That path additionally requires scopeText, keeps the default blank-line separator and position: "after", and accepts a fixed HTML subset rather than anything Notes.app can render:

Ordinary notes take the guarded HTML path and are not restricted to that subset.

insert-link

Adds one web, mail or Notes link to an exact note as its own paragraph, then proves it from the link runs Notes actually stored. Use mode: "raw" to show the URL itself, or mode: "hyperlink" with a label to show text that links to the URL. For a link to another note by id, use insert-note-link, which looks up that note's real deep link.

Example - Hyperlink under the title:

{
  "id": "x-coredata://ABC123/ICNote/p456",
  "expectedContentHash": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "url": "https://example.com/report",
  "mode": "hyperlink",
  "label": "Quarterly report",
  "position": "after-title"
}

Returns: route ("applescript" for ordinary notes, "native" for notes with native objects), linkStored, storedUrl (the destination read back from the note, for example https://example.com/ for a bare origin), and the new contentHash.

Safety: The same guards as append-to-note: a fresh expectedContentHash, the attachment block, and every existing link must survive. A linked insert must add exactly one stored link with the requested label and destination; if the text lands but that proof fails, the error says the write happened so it is not repeated.

Limits:

• Plain URL text is not linked by Notes when written this way. With linked: false, the note stores no link and readers of the body see ordinary text; Notes.app may still underline the URL on screen through its own data detection. The result reports linkStored: false.
• Notes with native objects (a table, a checklist, native tags) take the native end-append path, so only position: "end" with blankLine: true works there.
• The link always gets its own paragraph. Placing it at the end of one existing paragraph, or inside the text, is not available.
• Rich URL preview cards (the link tile Notes makes when you paste a URL) are not produced. No public automation route creates one: the Shortcuts Notes actions write text, and AppleScript's body has no card markup.
• To start a new note with a link, use create-note with format: "html" and an <a href> in content; the link is stored the same way.

get-note-link

Returns the notes://showNote?identifier=<uuid> deep-link URL for a note. The URL opens the note in Notes.app on iOS and macOS and can be stored in Reminders tasks or shared links.

Note: Either id or title must be provided. Using id is recommended. Password-protected notes cannot be linked.

Example:

{
  "id": "x-coredata://ABC123/ICNote/p456"
}

Returns: notes://showNote?identifier=<uuid> URL string, plus the note id and title.

Note: Requires Full Disk Access for the process that runs the server so the Notes SQLite database is readable. On macOS 12–15 the tool also falls back to the AppleScript note link property. Run the doctor tool to verify access.

list-notes

Lists all notes, optionally filtered by folder, date, and limit.

Example - All notes:

{}

Example - Notes in a folder:

{
  "folder": "Work"
}

Example - Recent notes with limit:

{
  "modifiedSince": "2025-06-01",
  "limit": 20
}

Returns: List of notes as {title, id} pairs — notes: Array<{title, id}>, plus count. The human-readable line is - <title> [id: <id>]. Notes in Recently Deleted are left out by default and counted in excludedRecentlyDeleted (present only when nonzero); with includeRecentlyDeleted: true they are listed with inRecentlyDeleted: true and a [RECENTLY DELETED] marker. Notes.app's own listing includes them, so the Recently Deleted folder is recognised by its database id (with Full Disk Access) or by its English name. With Full Disk Access each entry also carries identifier, folderIdentifier, and accountIdentifier (see Identifier forms).

Use the returned id for any follow-up read/update/move/delete rather than re-resolving the title: titles are not unique, and a by-title lookup resolves a duplicated title to the same one note every time, silently skipping the others.

Changed in 2.7.0: notes was previously string[] (titles only). Callers that treated the array as strings must now read .title.

For date order, incremental sync cursors, Recently Deleted, or word counts, use list-recent-notes.

list-recent-notes

Lists notes from the NoteStore database (read-only) by stored modification time, with an exact cursor for incremental sync. With since, it pages through changes oldest first; without it, it shows the newest notes first. Unlike list-notes, it can include Recently Deleted and can count words.

Requires: Full Disk Access for the MCP host process (see Full Disk Access Setup).

Returns: notes, each with id, identifier, title, folder, account, created, modified, modifiedCheckpoint, pinned, locked, inRecentlyDeleted, and markedForDeletion. Also count, limit, order (oldest-first or newest-first), saturated, and nextSince.

• Cursors. modifiedCheckpoint is an opaque token (cdts1:, 16 hex digits, :, the note's database key). It carries the exact stored timestamp bits, so it never loses precision the way an ISO string can, and the key orders notes that share one timestamp. Pass it back as since.
• Syncing. Call with since, store nextSince, and pass it as the next since. nextSince is the last returned row's cursor, or the incoming boundary when nothing matched, so every call advances. saturated is true when count equals limit: more changes may follow, so call again right away. When it is false, you are caught up. Notes that share a timestamp are split across pages by key, so none is skipped or repeated.
• First sync. Start with since: "1970-01-01" and page the same way. A library larger than the 1000-row maximum is reached in full.
• Browsing. Without since, rows come newest first. nextSince is then the newest row's cursor, set only when the call returned every matching note (saturated is false); otherwise it is null.
• Late edits. A modification-date cursor can miss an edit that iCloud delivers later from another device with an older timestamp, for example after that device was offline. The row then sorts before the cursor. Run a full pass from the start now and then to catch these.
• Deletions. Deleted notes are invisible unless includeDeleted is true. With it, notes in Recently Deleted and notes awaiting deletion appear, flagged, when their modification date is after the cursor. A note purged from the database leaves no row, so compare ids against a full pass to detect it.
• Word counts. A word is a whitespace-separated token containing a letter or digit, except that Chinese, Japanese, Thai, Lao, Khmer and Myanmar text, which has no spaces between words, is split at word boundaries (the same count query-notes uses for words: and wordCount); charCount counts Unicode code points. Attachment markers are not counted. Both are null for locked notes and bodies that are not downloaded or cannot be decoded, and 0 for a body known to be empty.
• Previews. With wordCounts, bodyPreview comes from the decoded body and textDecoded is true. Otherwise it is the stored snippet. Locked notes never get a preview.
• Folderless notes (abandoned Quick Note drafts Notes.app never shows) and Recently Deleted appear only with includeDeleted. Notes without a stored modification date never match a since query.

Example - incremental sync:

{
  "since": "cdts1:41c7e0ef438fcd6f:4312",
  "limit": 200
}

get-selected-notes

Reads the currently selected note(s) from the Notes.app UI.

Parameters: None

Returns: Selected note metadata, including IDs for follow-up operations. Returns an empty list when Notes.app has no selected note.

Folder Operations

list-folders

Lists all folders in an account with full hierarchical paths.

Example:

{}

Returns: List of folders with IDs, paths, account names, and shared state, plus identifier, parentIdentifier, and accountIdentifier when Full Disk Access is granted. Nested folders are shown as full paths (e.g., Work/Clients/Omnia). Duplicate folder names are disambiguated by their full path. Literal slashes in folder names are escaped as \/ (e.g., Spain\/Portugal 2023). Smart folders are listed too, because Notes' AppleScript lists them like ordinary folders; with Full Disk Access they carry smartFolder: true (and (smart folder) in the text list). A smart folder cannot hold notes or folders.

list-smart-folders

Lists every Smart Folder with the rules that define it, read from the NoteStore database. Requires Full Disk Access.

Example:

{
  "includeMatchingNotes": true,
  "limit": 20
}

Returns: For each smart folder: name, id, identifier, account, accountId, accountIdentifier, parent, parentId, and parentIdentifier (the parent fields are null at the account root). Its rules are decoded as match ("all", "any", or "none") and filters. Each filter has a type (the stored rule key, such as folder, tag, checklist, or creationDateRelativeRange), its stored value, excluded for an Exclude rule, and a readable description. Folder filters add the folder's name and folderId, and a nested rule group is a filter of type group with its own match and filters. Notes stores each query inside an outer {"deleted": false} wrapper that keeps Recently Deleted out. query is the stored query with that wrapper removed, includesRecentlyDeleted reports the wrapper's value, and rawQuery is the stored JSON verbatim. A rule this server does not recognize is kept as a filter of type unknown, and fullyDecoded is then false.

With includeMatchingNotes, each folder also carries matchingNoteCount and matchingNotes (title and id). These come from Notes.app itself, which evaluates the folder's rules, so they need Automation permission. The server does not re-evaluate the rules on its own. A folder whose notes cannot be read carries matchingNotesError instead.

list-folder-tree

Returns the folder hierarchy with note counts for each account, read from the NoteStore database in one pass.

Requires: Full Disk Access for the MCP host process (see Full Disk Access Setup).

Returns: accounts, each with account, identifier, noteCount, and folders. Each folder node has id, identifier, name, path (in list-folders syntax), kind (folder, smart, or trash), noteCount (notes directly inside), totalNoteCount (including subfolders), and children. Regular folders sort by name, then smart folders, then Recently Deleted. An account's noteCount sums its regular folders. Smart folders report 0 because their contents are a saved search. Also returns folderCount.

create-folder

Creates a new folder, including a whole nested hierarchy in one call.

Example:

{
  "name": "Work Projects"
}

Example - Create a nested hierarchy:

{
  "name": "Work/Clients/Omnia"
}

Returns: Confirmation message. The call is idempotent — an already-existing folder (or path segment) is skipped rather than treated as an error, so it is safe to call before every create-note that targets a folder.

Existence is decided by folder id, not by name: a folder deleted earlier in the same Notes session no longer counts as existing, and the call succeeds only once the created folder is confirmed by its id. Otherwise it reports failure.

get-folder-by-id

Reads one exact folder's current name, parent ID, and account ID (accountId, plus isRoot, true when the folder sits at the account root). Use these values with rename-folder or delete-folder-by-id; this avoids relying on ambiguous folder names or paths. The id may also be the folder's Notes UUID or numeric key, and the result adds identifier, parentIdentifier, and accountIdentifier when Full Disk Access is granted.

rename-folder

Renames an existing folder in place using its exact id, expectedName, expectedParentId, and newName. The operation preserves the folder ID, notes, and descendants. It refuses stale metadata and a conflicting sibling name.

delete-folder-by-id

Deletes one exact, empty, ordinary folder through a plan-then-apply handshake. Read the folder first with get-folder-by-id, call once with dryRun: true, then repeat the same guards with dryRun: false and the returned revision.

Example (plan, then apply with the returned revision):

{
  "id": "x-coredata://ABC/ICFolder/p42",
  "expectedName": "Old Projects",
  "expectedAccountId": "x-coredata://ABC/ICAccount/p3",
  "expectedRoot": true,
  "dryRun": true
}

Returns: status: "planned" with wouldDelete, identifier, name, accountId, parentId, folderType: 0, zero childFolderCount and noteCount, and revision; on apply, status: "deleted", committed: true, verified: true (Notes.app no longer resolves the id), and storeTombstoned.

Safety: it always refuses Recently Deleted, smart folders, the account's default and other system folders, shared folders (or folders inside a shared folder), and any folder that still holds notes or subfolders. There is no override. It is not atomic: the guard is a pre-check followed by an AppleScript delete. The name, parent, account, sharing, and emptiness checks repeat inside the delete script, but the folder type and stable identifier come from the local Notes database just before it. It needs Full Disk Access and fails closed without it.

Errors carry the standard code: revision_conflict (a Conflict: message; read and plan again), unsupported (a Refused: message), verification_failed with indeterminate: true (read the folder before any retry), and full_disk_access_missing.

delete-folder

Deletes a folder.

Example:

{
  "name": "Old Projects"
}

Returns: Confirmation message, or error if folder not found or not empty.

⚠️ Safety: Irreversible — requires explicit user confirmation before calling. Prefer list-folders first to confirm the exact folder path being deleted.

show-folder

Reveals a folder in Notes.app using its unique CoreData identifier.

Returns: Confirmation that Notes.app accepted the show command.

Account Operations

list-accounts

Lists all configured Notes accounts.

Parameters: None

Example:

{}

Returns: List of accounts with names, IDs, upgraded state, and default folder metadata, plus each account's identifier (Notes UUID) when Full Disk Access is granted.

get-default-location

Returns the default account and folder Notes.app uses for newly created notes.

Parameters: None

Returns: Default account and folder metadata, including IDs and shared state.

show-account

Reveals an account in Notes.app using its unique CoreData identifier.

Returns: Confirmation that Notes.app accepted the show command.

Batch Operations

batch-delete-notes

Deletes multiple notes at once by ID.

Returns: Summary of successes and failures. A note already in Recently Deleted fails without being deleted, as in delete-note.

⚠️ Safety: Irreversible — requires explicit user confirmation before calling. Prefer search-notes / list-notes first to confirm the exact ids being deleted.

batch-move-notes

Moves multiple notes to a folder.

Returns: Summary of successes and failures. Each success is reported only after the note's actual container folder ID matches the destination folder ID.

Export Operations

export-notes-json

Exports notes as JSON — metadata, HTML content, and plaintext, grouped by account and folder — one page at a time. A whole library rarely fits in one MCP message (note bodies embed images as base64), so each call returns a page and says where the next one starts.

Example - First page:

{}

Example - A later page of an incremental backup:

{
  "offset": 50,
  "modifiedSince": "2025-06-01"
}

Returns: exportDate, version, accounts (every account and folder, holding the notes that fall in this page), summary (totalNotes in this page, totalFolders, totalAccounts), and page:

Size limit: each response stays under APPLE_NOTES_MCP_EXPORT_MAX_BYTES (default 8 MB), below the 10 MB per-message limit of MCP SDK stdio clients, which drop the connection on anything larger without passing on any error text. A note too large to fit on its own is still returned: its oversized inline images are replaced with placeholders (strippedImages), or failing that its HTML body, and if necessary its plaintext, is left empty with contentOmitted: true. Read such a note with get-note-content, and its files with list-attachments / save-attachment. Lower limit if your MCP client caps tool output below that size.

Paging: positions are worked out on every call, so notes created, deleted, or moved between calls can shift a page. Page through promptly, or use modifiedSince for incremental backups.

get-note-markdown

Gets a note's content as Markdown instead of HTML. If the note contains checklists and Full Disk Access is granted, checklist items are automatically annotated with [x] (done) or [ ] (undone).

Returns: Note content converted to Markdown format. Checklist items include [x]/[ ] prefixes when database access is available.

export-notes-markdown

Exports one note, or the notes of one folder, as a single Markdown document rendered from the decoded note body (the same block model as get-note-blocks). Titles render as #, headings as ##, subheadings as ###. Bulleted, dashed and numbered lists keep their indent (four spaces per level), checklists render as - [x]/- [ ], block quotes as >, and monospaced paragraphs as fenced code. Inline runs keep bold, italic, strikethrough, underline (<u>), highlight (==), superscript and subscript (<sup>/<sub>), and links whose scheme is http(s), notes:, applenotes: or mailto:. Tables render as GitHub tables. Attachments stay in body order: with assetsDir they link to copies of their files (images inline, drawings through Notes' fallback image, scans as their PDF), and without it they render as labeled placeholders such as \[Image: name\]. An attachment whose file cannot be found renders as \[Image unavailable: name\]. Body text that Markdown would read as block syntax (a leading # to ######, >, -, +, *, 1. or 1), a --- line, a code fence or a table row) is backslash-escaped, so a plain paragraph such as ## Notes stays a paragraph, and wrap never starts a continuation line with such a marker. This tool leaves get-note-markdown unchanged.

A folder export is one presentation document with notes separated by ---. It is not a backup or restore format; use export-notes-json for that.

Requires: Full Disk Access. Password-protected notes are skipped in a folder export (listed in skipped with code encrypted) and refused for a single note.

Both paths follow the save-attachment rules (absolute, under the home directory, a temp directory, or /Volumes, no symlink escapes) and may not point inside the Notes library container. templateFile is a read, so it also follows contentPath's private-location rule. With outputPath, asset links are relative to the document's directory; without it they are absolute paths.

Returns: without outputPath, the Markdown itself (refused with [too-large] above half of APPLE_NOTES_MCP_EXPORT_MAX_BYTES, because the document travels in both the text and structured result). With outputPath, a receipt: format, count, bytes, output, and assets (dir, files). Both carry stats (attachments, placed, placeholders, unavailable, tables, unreadableTables, unreferenced) and skipped. Nothing already written is deleted if a later step fails.

Templates: template or templateFile renders through a portable JSON template that sets how every block style, inline format, attachment, per-note header and footer (for YAML front matter with title, dates, folder, tags and id), and the note separator are written. The built-in standard-markdown reproduces the default output; obsidian adds front matter and copies attachments into <file>.assets beside outputPath. Templated asset copies get stable content-hashed names and are reused on a repeat export. An invalid template is refused with [invalid-template] and one JSON path per problem, before any note is read. A templated receipt adds template, warnings (such as missing_asset) and assetFiles. See docs/markdown-templates.md for the schema, every rule and placeholder, and examples.

export-notes-html

Exports one note, or the notes of one folder, as one standalone HTML file rendered from the decoded note body. It uses the same block model and attachment handling as export-notes-markdown. Headings become h1-h3, lists nest by indent as ul/ol, checklists show disabled checkboxes, block quotes and monospaced paragraphs become blockquote and pre, and inline runs keep bold, italic, underline, strikethrough, highlight, superscript, subscript, text color and safe links. Tables are semantic <table> elements with a header row. Images, drawings (Notes' fallback image, or its preview), scans (PDF with preview), audio, video, files and link cards (title, domain and preview thumbnail) appear in body order. Attachments with no body marker are appended in creation order. An attachment with no usable source renders a visible [Image unavailable: name] marker. The document contains no script, no file: URL and no Notes library path.

A folder export is one presentation document with notes separated by <hr class="note-separator">. It is not a backup or restore format.

Requires: Full Disk Access. Password-protected notes are skipped in a folder export and refused for a single note.

The HTML is always written to a file, because an embedded document is too large for an MCP message. Paths follow the save-attachment rules and may not point inside the Notes library container. Sidecar URLs are relative to the HTML file, so the file and its .assets directory can be moved together.

Returns: format, count, bytes, output, either embedded (assets embedded) or assets (dir, files), stats, and skipped. Nothing already written is deleted if a later step fails.

list-markdown-templates

Lists the Markdown export templates: the built-ins (standard-markdown, obsidian) and every saved template in the library, with its display name, description, size and modification date. Unreadable, invalid or unsafe files in the library are skipped and counted in skipped. Takes no parameters.

Returns: builtins, templates, skipped, and dir (the library directory).

show-markdown-template

Returns one template in its portable form: a built-in, or a saved template exactly as stored (overrides only). Use it as the starting point for a new template.

Returns: name, source (builtin or saved), template, and optionally expanded.

validate-markdown-template

Checks a template without saving it. Pass exactly one of name, template or templateFile.

Returns: valid, and errors as {path, message} pairs such as $.rules["inline.bold"].after: is required when mode is "wrap". An invalid template is a normal result, not a tool error.

save-markdown-template

Validates a template and stores it in the library so export-notes-markdown can use it by template name.

Saving is create-only: an existing name is refused with [template-exists] unless force is true. An invalid template is refused with [invalid-template] and one JSON path per problem. The file is written to a temporary name and then moved into place, with mode 0600 in a 0700 directory. The library is ~/Library/Application Support/apple-notes-mcp/templates, or APPLE_NOTES_MCP_TEMPLATE_DIR. A symlinked library or template file is refused.

Returns: name, path, bytes, and replaced.

delete-markdown-template

Removes one saved template file from the library. Built-in templates cannot be deleted.

Returns: name, path, and deleted: true.

get-checklist-state

Reads checklist done/undone state for a note. This bypasses the AppleScript limitation where body of note strips checklist state, by reading directly from the NoteStore SQLite database.

Requires: Full Disk Access for the MCP host process (see Full Disk Access Setup).

Example:

{
  "id": "x-coredata://ABC123/ICNote/p456"
}

Returns: Checklist items with done/undone state and progress count:

Checklist for "Shopping List" (2/4 done):
[x] Buy milk
[x] Get bread
[ ] Pick up laundry
[ ] Call dentist

get-note-metadata (BETA)

Reads note metadata that AppleScript cannot expose, by querying the NoteStore SQLite database directly: pinned state, checklist flags, trash/recovery state, the preview snippet, and the password hint. The available fields vary by macOS version.

Requires: Full Disk Access for the MCP host process (see Full Disk Access Setup).

BETA: the NoteStore schema changes between macOS releases, so some fields can be absent on older or newer systems. The database is only ever read, never written.

Returns: A metadata object in structuredContent holding any of pinned, hasChecklist, hasChecklistInProgress, recoveringFromTrash, passwordProtected, passwordHint, snippet, widgetSnippet, and smartFolderQuery. Unlike most read tools, it also resolves trashed notes that AppleScript can no longer find.

list-special-notes

Lists a set of notes that AppleScript cannot enumerate: pinned notes, Quick Notes, notes in Recently Deleted, or password-protected notes. It reads the NoteStore database read-only and returns metadata only, never body text.

Requires: Full Disk Access for the MCP host process (see Full Disk Access Setup).

Returns: notes, newest first, each with id, identifier (Notes UUID), title, folder (path in list-folders syntax, or null), account, created, modified, and the flags pinned, locked, quickNote, inRecentlyDeleted, and markedForDeletion. Unlocked rows add the stored snippet. The locked listing adds passwordHint when one is set. Also returns count, total (matches before limit), limit, and supported.

• pinned and quick-notes cover notes in folders outside Recently Deleted. Folderless Quick Note drafts, which Notes.app never shows, are left out.
• recently-deleted lists notes in each account's Recently Deleted folder and skips tombstones already waiting to sync away.
• locked lists every password-protected note, including trashed and folderless ones, so a misplaced locked note can still be found. Their flags and folder say where each one is.
• supported: false means this macOS version's database has no column for that kind (for example, Quick Notes before macOS 12).

get-audio-transcripts

Reads the transcript, and the summary when one exists, that Notes already computed for the audio recordings in a note. It does not transcribe anything itself. Notes keeps each recording's transcript as word-level mergeable data on the audio attachment's database row, and this tool decodes it read-only.

Requires: Full Disk Access for the MCP host process (see Full Disk Access Setup). Password-protected notes are refused.

Example:

{
  "id": "x-coredata://ABC123/ICNote/p456",
  "includeSegments": true,
  "maxSegments": 500
}

Returns: structuredContent.attachments holds one entry per top-level audio attachment, in the order the recordings appear in the note. Each entry has:

• attachmentId (usable with save-attachment), identifier, typeUti, and durationSeconds when known
• status: ok (a transcript is stored), none (no transcript is stored, for example a recording Notes has not transcribed, or an audio file attached from elsewhere), or undecodable with a reason
• text (the words joined into readable text), wordCount, fragmentCount, speakers, summary and topLineSummary when stored, and needsTranscription when the database records it
• segments, only when includeSegments is set, with segmentsTruncated when the cap cut them short

A recording extended with more takes has several fragments. Their transcripts are joined in stored order, separated by a blank line, and each segment carries a fragment index. Recordings with more than one fragment have been verified against synthetic fixtures only. A response that would exceed APPLE_NOTES_MCP_EXPORT_MAX_BYTES (default 8 MB) drops segments first and then shortens text, marking truncated, segmentsTruncated and textTruncated. When the note body cannot be parsed, attachments come back in database order with bodyOrder: false.

get-note-drawings

Decodes a note's classic PencilKit drawings (com.apple.drawing.2 and the older com.apple.drawing attachments) into strokes and SVG. The PencilKit bytes are read read-only from the NoteStore database and decoded by Apple's public PKDrawing(data:) in the public native helper. Modern Paper sketches (com.apple.paper) are a different format and are not decoded here.

Requires: Full Disk Access for the MCP host process, and the public native helper built once with apple-notes-mcp setup --public-helper.

Returns: status (ok, partial, error, or none when the note has no classic drawing), drawingCount, and one entry per drawing with attachmentId, identifier, typeUti, status (ok, or error with a code such as no_data, undecodable, or timeout), strokeCount, bounds, truncated, strokes (each with inkType, sRGB color with alpha, mean width, pointCount, bounds, and points), and svg. Points are already in drawing coordinates. Ink removed with the pixel eraser is left out: a partly erased stroke comes back as one entry per visible piece, each marked masked: true, and hiddenStrokeCount counts strokes erased completely. pointsTruncated: true marks a stroke cut short by the helper's point limit. When a response would exceed APPLE_NOTES_MCP_EXPORT_MAX_BYTES, points are dropped and pointsOmitted is set, then SVG documents are dropped and svgOmitted is set; if it still does not fit, the call fails with an error instead. The SVG draws one path per stroke; it is a faithful outline, not a pixel-exact copy of PencilKit's ink textures.

transcribe-note-audio

Transcribes a note's voice recordings and audio attachments now, on this Mac, with Apple's Speech framework through the public native helper. Recognition is on-device only: SpeechAnalyzer on macOS 26 and later, or SFSpeechRecognizer with on-device recognition required on older systems (a locale without on-device support is refused, never sent to a server). The audio files are opened read-only where Notes keeps them.

Requires: Full Disk Access for the MCP host process, and the public native helper built once with apple-notes-mcp setup --public-helper.

Returns: Overall status and, per audio attachment, status, durationSeconds, wordCount, transcript, and takes (a Notes recording can hold several takes; each is transcribed and the texts are joined in stored order). Statuses:

• ok: the whole recording was transcribed.
• partial: some text came back, but a take failed or the helper stopped at its deadline (code: "incomplete").
• error: nothing was transcribed; code says why (asset_unavailable when the audio file is not on this Mac or the language's speech model is not installed, permission_required, unsupported_locale, unsupported_audio, time_limit, ...).
• indeterminate: the helper did not answer in time, so the outcome is unknown and a retry may succeed.
• none (overall only): the note has no audio.

Each take gets a deadline of 1.5 times its length plus a minute (at most 30 minutes), shortened to what is left of maxSeconds. A take that cannot start before the budget runs out reports code: "time_limit". The helper runs as a separate process without blocking the server, and cancelling the request stops it. On macOS 27 a 16-minute recording took about 22 seconds. Some MCP clients stop waiting for a tool after a fixed time, so transcribe long recordings one at a time with attachmentId. Transcripts longer than APPLE_NOTES_MCP_EXPORT_MAX_BYTES are shortened and marked transcriptTruncated.

Speech models: the call never starts a download on its own. When the language's on-device model is not installed, it returns asset_unavailable right away. Pass downloadAssets: true to let macOS download it (a one-time download); if it is still downloading when the call ends, try again shortly.

Speech Recognition permission: the server never shows the Speech Recognition prompt, because nobody may be watching an MCP server to answer it. The helper reads the current authorization first. On older macOS, the SFSpeechRecognizer path needs that access, and macOS attributes the grant to the app that launches the MCP server (Claude Desktop, Codex, Terminal, and so on), not to the helper. Without it the call returns code: "permission_required"; allow the app under System Settings > Privacy & Security > Speech Recognition. If the app has never asked for Speech Recognition access, macOS does not list it there yet, and the call returns code: "permission_not_requested" instead: use macOS 26 or later, or run the server from an app that already has the access. On macOS 26 and later, SpeechAnalyzer transcribed files without any grant in testing (authorization stayed "not determined"), so only an explicit refusal (denied or restricted) stops it.

add-attachment

Adds one nonempty local file of at most 64 MiB to an exact note using id, the latest expectedContentHash, and an absolute path. The server never retries the insertion. It verifies that existing rich content survived and compares the size and streamed SHA-256 of Notes' saved copy with the source before reporting success, with no read cap below the 64 MiB write limit.

| Parameter | Type | Required | Description | |-----------|------|----------|

…