apple-notes-mcp 2.9.20 → 2.9.22

package/README.md

@@ -1,6 +1,8 @@
 # Apple Notes MCP Server
 
-A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants like Claude to read, create, search, and manage notes in Apple Notes on macOS.
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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.
 
 [![npm version](https://img.shields.io/npm/v/apple-notes-mcp)](https://www.npmjs.com/package/apple-notes-mcp)
 [![npm downloads](https://img.shields.io/npm/dm/apple-notes-mcp)](https://www.npmjs.com/package/apple-notes-mcp)
@@ -15,6 +17,13 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that e
   <img src="https://raw.githubusercontent.com/sweetrb/apple-notes-mcp/main/codex/assets/screenshot.png" alt="Apple Notes MCP — create, search, and organize Apple Notes from Codex, Claude, and other AI assistants" width="680">
 </p>
 
+## Contents
+
+- [What is This?](#what-is-this) · [Quick Start](#quick-start) · [Requirements](#requirements) · [Features](#features)
+- [Tool Reference](#tool-reference): [notes](#note-operations), [folders](#folder-operations), [accounts](#account-operations), [batch](#batch-operations), [export, attachments, and media](#export-operations), [diagnostics](#diagnostics), [native background operations](#native-background-operations), [private helper](#private-helper-opt-in-unsupported-apple-api)
+- [Usage Patterns](#usage-patterns) · [Installation Options](#installation-options) · [Configuration](#configuration) · [Full Disk Access](#full-disk-access) · [Public native helper](#public-native-helper)
+- [Security and Privacy](#security-and-privacy) · [Known Limitations](#known-limitations) · [Troubleshooting](#troubleshooting) · [Recurring macOS permission prompts](#recurring-macos-permission-prompts) · [Development](#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:
@@ -25,7 +34,7 @@ This server acts as a bridge between AI assistants and Apple Notes. Once configu
 - "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. All data stays local on your machine.
+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
 
@@ -56,7 +65,7 @@ Install as a Claude Code plugin for automatic configuration and enhanced AI beha
 
 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 (`get-checklist-state`, `get-note-metadata`, `get-audio-transcripts`, `list-special-notes`, `list-native-tags`, `list-recent-notes`, `list-folder-tree`, `get-note-link`, checklist annotations in `get-note-markdown`, and full `get-sync-status` detail); see the [Full Disk Access Setup Guide](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/FULL-DISK-ACCESS.md). The rest of the server is pure AppleScript and works without it.
+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](#full-disk-access)); see the [Full Disk Access Setup Guide](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/FULL-DISK-ACCESS.md). 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:
@@ -148,6 +157,10 @@ npm install -g apple-notes-mcp
 
 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](#configuration-file-when-the-host-strips-env).
+
 ## Requirements
 
 - **macOS** - Apple Notes and AppleScript are macOS-only
@@ -158,24 +171,30 @@ On first use, macOS will ask for permission to automate Notes.app. Click "OK" to
 
 | Feature | Description |
 |---------|-------------|
-| **Create Notes** | Create notes with titles, content, and optional folder/account targeting |
+| **Create Notes** | Create notes from plaintext, HTML, or Markdown, with optional folder/account targeting (Markdown creation uses an optional Shortcut on macOS 26 or later) |
 | **Search Notes** | Find notes by title or search within note content |
 | **Query Language** | `query-notes` combines text, folder, account, tag, attachment, checklist, flag, word-count, and date conditions with AND/OR/NOT, read from the Notes database (requires Full Disk Access) |
-| **Read Notes** | Retrieve note content and metadata |
-| **Update Notes** | Modify existing notes (title and/or content) |
+| **Read Notes** | Retrieve note content as HTML, plain text, or Markdown, plus metadata that AppleScript does not expose (pinned, Quick Note, locked, Recently Deleted) |
+| **Note Structure** | Decode a note into typed paragraph blocks, list its paragraphs and links, and get a direct link to one paragraph (requires Full Disk Access) |
+| **Update Notes** | Replace, append to, or prepend to an existing note, guarded by a content hash so a note that changed since it was read is never overwritten |
 | **Delete Notes** | Remove notes (moves to Recently Deleted) |
 | **Move Notes** | Organize notes into folders (supports nested paths) |
-| **Folder Management** | Create, list, and delete folders with full hierarchical path support |
+| **Folder Management** | Create, list, rename, and delete folders with full hierarchical path support; read the folder tree with note counts and Smart Folder rules |
 | **Multi-Account** | Work with iCloud, Gmail, Exchange, or any configured account, including account IDs and default folders |
 | **Batch Operations** | Delete or move multiple notes at once |
-| **Checklist State** | Read checklist done/undone state directly from the Notes database (requires Full Disk Access) |
-| **Audio Transcripts** | Read the transcripts and summaries Notes stored for audio recordings (requires Full Disk Access) |
-| **Export** | Export all notes as JSON or get individual notes as Markdown |
-| **Attachments** | List attachments with their on-disk asset and preview paths, find a note's lead image, save or batch-export them to disk, or fetch their bytes as base64 |
-| **Notes.app UI State** | Reveal a note in Notes.app or read the current Notes.app selection |
+| **Native Tags** | List, add, remove, and replace real Notes tags (not just `#hashtag` text) |
+| **Checklists** | Read checklist done/undone state from the Notes database, and append real checklist items through a Shortcut |
+| **Tables** | Read native tables as Markdown and JSON, and append new native tables |
+| **Pinning** | Read pinned state and pin or unpin a note |
+| **Links** | Get a note's `notes://` deep link, insert web, mail, or note-to-note links, and list the links in a note or folder |
+| **Export** | Export notes as paginated JSON, or render a note or folder as Markdown (with reusable templates) or standalone HTML |
+| **Attachments** | Add files to notes (from a path or the pasteboard), list attachments with their on-disk paths, find a note's lead image, save or batch-export them, or fetch their bytes as base64 |
+| **Audio and Drawings** | Read the transcripts Notes stored for recordings, transcribe audio on-device, and decode drawings to strokes and SVG |
+| **Incremental Sync** | `list-recent-notes` pages through notes by modification time with an exact cursor |
+| **Notes.app UI State** | Reveal a note, folder, account, or attachment in Notes.app, or read the current Notes.app selection |
 | **Sync Awareness** | Detect iCloud sync in progress, warn about incomplete results |
 | **Collaboration** | Detect shared notes, warn before modifying |
-| **Diagnostics** | `health-check` plus a richer `doctor` (reachability, automation permission, accounts, Full Disk Access), sync status, and statistics |
+| **Diagnostics** | `health-check` plus a richer `doctor` (reachability, automation permission, accounts, Full Disk Access), sync status, statistics, and `get-capabilities` for the Shortcut bridges |
 
 Read/list/get tools also return **structured JSON** (`structuredContent`) alongside the text, so agents can consume results without parsing prose.
 
@@ -193,8 +212,8 @@ reading Notes' own database instead; the rest genuinely cannot be supported. See
 **[docs/APPLESCRIPT-LIMITATIONS.md](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/APPLESCRIPT-LIMITATIONS.md)**
 for the investigation and verification behind each:
 
-- **Pinned notes** — Notes has no scriptable `pinned` property via AppleScript. Pin state can now be **read** with the BETA `get-note-metadata` tool (from the NoteStore database), but it still cannot be **set** programmatically.
-- **Note-to-note links** — AppleScript exposes no link property or link element, so link *relationships* between notes cannot be read, and a link cannot be inserted into a note body. A shareable `notes://showNote?identifier=<uuid>` deep link **is** available via [`get-note-link`](#get-note-link).
+- **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`](#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`](#list-note-links), and inserted by [`insert-note-link`](#insert-note-link) (through a Shortcut) or [`insert-link`](#insert-link). A shareable `notes://showNote?identifier=<uuid>` deep link is available via [`get-note-link`](#get-note-link).
 
 ---
 
@@ -256,14 +275,14 @@ Creates a new note in Apple Notes.
 | `title` | string | Yes | The title of the note. Automatically prepended as `<h1>` — do NOT include the title in `content` |
 | `content` | string | One of `content`/`contentPath` | The body content of the note (do not repeat the title here) |
 | `contentPath` | string | One of `content`/`contentPath` | Absolute path of a local UTF-8 file to use as the body instead of `content`. Allowed in the same places [`save-attachment`](#save-attachment) may write (home, temp, `/Volumes`); symbolic links, non-regular files, invalid UTF-8 and files over 1 MiB are refused before anything is written. A leading byte-order mark is dropped |
-| `tags` | string[] | No | Returned-only metadata — **NOT written to Notes.app**. Apple Notes tags can't be set via AppleScript, so values passed here are echoed back in the response but do not appear on the created note. Use inline `#hashtags` in `content` instead (Notes.app turns those into real tags). Refused with `format: "markdown"` |
+| `tags` | string[] | No | Returned-only metadata — **NOT written to Notes.app**. Apple Notes tags can't be set via AppleScript, so values passed here are echoed back in the response but do not appear on the created note. Inline `#hashtags` in `content` stay searchable text and are returned as `hashtags`, but they do not become native Notes tags; add real tags afterwards with [`add-native-tags`](#add-native-tags). Refused with `format: "markdown"` |
 | `folder` | string | No | Folder to create the note in. Supports nested paths like `"Work/Clients"`. **The folder must already exist** — create it first with [`create-folder`](#create-folder). A smart folder is refused (see [`move-note`](#move-note)). Defaults to account root |
 | `account` | string | No | Account name (defaults to Notes.app's default account; matched exactly or by a *unique* prefix — an ambiguous prefix is refused). Must be an account Notes.app already has configured — see [`list-accounts`](#list-accounts) |
 | `format` | string | No | Content format: `"plaintext"` (default), `"html"`, or `"markdown"`. In all formats, the title is automatically prepended as the note's title line. In plaintext mode, newlines become `<br>`, tabs become `<br>`, and backslashes are preserved as HTML entities. `"markdown"` produces real Title/Heading/Subheading styles through a Shortcut; see [Markdown notes](#markdown-notes) |
 | `markdownRoute` | string | No | With `format: "markdown"` only: `"shortcut"` (default) or `"html"`. See [Markdown through HTML](#markdown-through-html) |
 | `timeoutSeconds` | number | No | Whole seconds, 1–120, for each Notes.app automation step this call runs; overrides `APPLE_NOTES_MCP_TIMEOUT_MS` for this call only. A timed-out write is uncertain, not failed: read the note by id before any retry. Also accepted by `get-note-content`, `update-note`, `append-to-note`, `delete-note` and `move-note` |
 
-**Example (tagged with inline hashtags):**
+**Example (with inline textual hashtags):**
 ```json
 {
   "title": "Meeting Notes",
@@ -587,8 +606,9 @@ base64 images larger than `APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES` (default
 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 refuses update and append operations on
-attachment-bearing notes; edit them in Notes.app.
+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.
 
 ---
 
@@ -600,6 +620,10 @@ 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.
 
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Exact note ID, in any [identifier form](#identifier-forms) |
+
 ---
 
 #### `get-note-tables`
@@ -860,6 +884,13 @@ 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`](shortcuts/README.md).
 
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Exact note ID, in any [identifier form](#identifier-forms) |
+| `expectedContentHash` | string | Yes | `contentHash` from a fresh read of the note |
+| `scopeText` | string | Yes | Distinctive phrase already in the note, 12–500 characters |
+| `tags` | string[] | Yes | 1–100 tag names to add |
+
 ---
 
 #### `get-note-plaintext`
@@ -947,6 +978,7 @@ Updates an existing note's content and/or title.
 | `format` | string | No | Content format: `"plaintext"` (default) or `"html"`. When `"html"`, content replaces the entire note body as raw HTML and `newTitle` is ignored (the first HTML element serves as the title) |
 | `allowLinkChanges` | boolean | No | Set to `true` only when intentionally changing or removing existing links |
 | `ifFolderId`, `ifAncestorFolderId`, `forbiddenAncestorFolderIds` | string, string, string[] | No | Folder preconditions; see [Folder scope guards](#folder-scope-guards) |
+| `timeoutSeconds` | number | No | Per-call timeout, 1–120 seconds, as for [`create-note`](#create-note). A timed-out write is uncertain: read the note by id before any retry |
 
 Title-only updates are rejected because Apple Notes titles are not unique.
 
@@ -992,6 +1024,7 @@ Deletes a note (moves to Recently Deleted in Notes.app).
 | `id` | string | Yes | Exact CoreData note ID returned by a read or search |
 | `expectedContentHash` | string | Yes | `contentHash` from the exact note version being deleted |
 | `ifFolderId`, `ifAncestorFolderId`, `forbiddenAncestorFolderIds` | string, string, string[] | No | Folder preconditions; see [Folder scope guards](#folder-scope-guards) |
+| `timeoutSeconds` | number | No | Per-call timeout, 1–120 seconds, as for [`create-note`](#create-note). A timed-out write is uncertain: read the note by id before any retry |
 | `guardNoteId` | string | No | A second note (usually a verified copy) that must still be intact; needs Full Disk Access |
 | `expectedGuardContentHash` | string | With `guardNoteId` | `contentHash` of the guard note from `get-note-content` |
 | `requireActiveNoteId` | string | No | A second note that must still exist, be unlocked, stay outside Recently Deleted, and not be a Quick Note; its content is not fingerprinted. Needs Full Disk Access |
@@ -1055,7 +1088,9 @@ A smart folder is never a destination: it only gathers notes by its rules, and N
 |-----------|------|----------|-------------|
 | `id` | string | Yes | Exact CoreData note ID returned by a read or search |
 | `folder` | string | Yes | Destination folder name or nested path (e.g., `"Work/Clients"`) |
+| `account` | string | No | Account whose `folder` is the destination (default: the default account) |
 | `ifFolderId`, `ifAncestorFolderId`, `forbiddenAncestorFolderIds` | string, string, string[] | No | Folder preconditions; see [Folder scope guards](#folder-scope-guards) |
+| `timeoutSeconds` | number | No | Per-call timeout, 1–120 seconds, as for [`create-note`](#create-note). A timed-out write is uncertain: read the note by id before any retry |
 
 Title-only moves are rejected.
 
@@ -1113,7 +1148,9 @@ Appends or prepends content to an existing note without replacing it. Always rea
 | `position` | string | No | `"after"` (default) appends to the end; `"before"` inserts directly below the note's title line, so the title stays first |
 | `separator` | string | No | String placed between existing content and new content (default: two newlines → `<div><br></div>` in HTML) |
 | `format` | string | No | Format of the content being appended: `"plaintext"` (default) or `"html"` |
+| `scopeText` | string | Native-object notes only | Unique existing phrase, as for [`append-native`](#append-native) |
 | `ifFolderId`, `ifAncestorFolderId`, `forbiddenAncestorFolderIds` | string, string, string[] | No | Folder preconditions; see [Folder scope guards](#folder-scope-guards) |
+| `timeoutSeconds` | number | No | Per-call timeout, 1–120 seconds, as for [`create-note`](#create-note). A timed-out write is uncertain: read the note by id before any retry |
 
 Title-only appends are rejected.
 
@@ -2354,6 +2391,15 @@ distinctive existing `scopeText` so the Shortcut and server can independently
 resolve the same note. Creating a note from Markdown is
 [`create-note`](#create-note) with `format: "markdown"`.
 
+Every tool below that edits one note takes these parameters, plus the ones
+listed under the tool itself:
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Exact note ID: x-coredata id, Notes UUID, or numeric key (see [Identifier forms](#identifier-forms)) |
+| `expectedContentHash` | string | Yes | `contentHash` (`sha256:…`) from a fresh read of the note |
+| `scopeText` | string | Yes | Distinctive phrase already in the note, 12–500 characters, that Notes search can find. Prefer plain words without punctuation, hashtags, or paths |
+
 When the Shortcut refuses a request (its Find Notes step did not return
 exactly one note with that exact title and `scopeText`) or stops with its own
 action error, and the note reads back unchanged, the tool reports the
@@ -2418,11 +2464,20 @@ unapproved bridge is identified rather than guessed at; a timeout also says it
 may be an unanswered first-run consent prompt and names the Shortcut to run once
 in the foreground.
 
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `content` | string | Yes | Content to append, up to 1,048,576 characters |
+| `format` | string | No | `"plaintext"` (default), `"html"`, or `"markdown"` |
+
 #### `create-checklist-item`
 
 Appends one real unchecked Notes checklist item and verifies its native identity
 and text.
 
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `text` | string | Yes | The item's text |
+
 #### `create-checklist-items`
 
 Appends several real unchecked checklist items, 1 to 20, in the order given.
@@ -2462,27 +2517,54 @@ cell. It never substitutes a text table. Omit `rows` for an empty 2 × 2 table,
 the size Notes itself inserts from Format > Table; its four empty cells are
 verified the same way.
 
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `rows` | string[][] | No | Cell text, row by row: 1–1,000 rows of 1–100 cells, every row the same length. Omit for an empty 2 × 2 table |
+
 #### `set-note-pinned`
 
 Sets an explicit pinned state after checking both the expected current state and
 the note revision. It does not rewrite the body.
 
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `expectedPinned` | boolean | Yes | The pinned state you last read; the call is refused if it differs |
+| `pinned` | boolean | Yes | The pinned state to set |
+
 #### `remove-native-tags`
 
 Removes specified tags from one exact note while preserving unrelated tags and
 native objects. It does not delete global tag definitions.
 
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `tags` | string[] | Yes | 1–100 tag names to remove |
+
 #### `replace-native-tag`
 
 Adds and verifies the new tag before removing the old tag on an explicit list of
 freshly read notes. Stops on the first uncertain result. Smart Folder rules are
 not changed.
 
+Unlike the other tools in this section, it takes a list of notes instead of one
+`id`:
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `notes` | object[] | Yes | 1–100 entries, each with the note's `id`, `expectedContentHash`, and `scopeText` |
+| `oldTag` | string | Yes | Tag to remove after the new one is verified |
+| `newTag` | string | Yes | Tag to add |
+
 #### `insert-note-link`
 
 Retrieves another note's real deep link and appends it with a static label while
 preserving the target note's native objects.
 
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `linkedNoteId` | string | Yes | ID of the note to link to, in any [identifier form](#identifier-forms) |
+| `label` | string | No | Visible link text (default: the linked note's title) |
+
 ### Private helper (opt-in, unsupported Apple API)
 
 An optional, **read-only** native helper reads note state through Notes' own
@@ -2675,8 +2757,14 @@ All configuration is optional — the server works out of the box. Override beha
 | `APPLE_NOTES_MCP_RETRY_DELAY_MS` | `1000` (1 s) | Base delay before the first retry; subsequent retries back off exponentially (1s, 2s, 4s, ...). |
 | `APPLE_NOTES_MCP_ENABLE_PRIVATE` | unset | Set to `1` to allow the opt-in [private helper](#private-helper-opt-in-unsupported-apple-api). Any other value keeps it off. |
 | `APPLE_NOTES_MCP_PRIVATE_HELPER_DIR` | `~/Library/Application Support/apple-notes-mcp/private-helper` | Where `setup --native-helper` installs the helper and its checksum manifest. |
-| `APPLE_NOTES_MCP_PRIVATE_HELPER_TIMEOUT_MS` | `20000` (20 s) | Per-call helper timeout. A timed-out write is indeterminate. |
+| `APPLE_NOTES_MCP_PRIVATE_HELPER_TIMEOUT_MS` | `20000` (20 s) | Per-call timeout for the private helper. The helper is read-only, so a timeout changes nothing in Notes. |
 | `APPLE_NOTES_MCP_PRIVATE_STORE` | unset | Testing only: points the helper at a **copy** of `NoteStore.sqlite`. The helper refuses a path that resolves to the live store. |
+| `APPLE_NOTES_MCP_PUBLIC_HELPER_DIR` | `~/Library/Application Support/apple-notes-mcp/public-helper` | Where `setup --public-helper` installs the [public native helper](#public-native-helper) and its checksum manifest. |
+| `APPLE_NOTES_MCP_PUBLIC_HELPER_TIMEOUT_MS` | `30000` (30 s) | Per-call timeout for the public native helper (`get-note-drawings`, `transcribe-note-audio`). |
+| `APPLE_NOTES_MCP_TAGS_SHORTCUT` | `Apple Notes MCP - Native Tags` | Name or UUID of the installed Native Tags bridge to run. `setup` still installs and checks the default name. |
+| `APPLE_NOTES_MCP_BACKGROUND_SHORTCUT` | `Apple Notes MCP - Background Operations v5` | Name or UUID of the installed Background Operations bridge to run. `setup` still installs and checks the default name. |
+| `APPLE_NOTES_MCP_MARKDOWN_SHORTCUT` | `Apple Notes MCP - Create Markdown Note` | Name or UUID of the installed Create Markdown Note bridge to run. `setup` still installs and checks the default name. |
+| `APPLE_NOTES_MCP_PASTEBOARD_NAME` | unset | Testing only: makes [`add-attachment-from-pasteboard`](#add-attachment-from-pasteboard) read a private named pasteboard instead of the general clipboard. |
 | `DEBUG` / `VERBOSE` | unset | Set either to enable verbose diagnostic logging to stderr. |
 
 ### Configuration file (when the host strips `env`)
@@ -2703,7 +2791,7 @@ MCP stores no secrets, but as a general rule keep only non-secret config here.
 
 ## Full Disk Access
 
-Several tools read directly from the Apple Notes SQLite database, which lives in a macOS-protected directory. Those tools require **Full Disk Access** for the process running the MCP server: `get-checklist-state`, `get-note-metadata`, `get-note-blocks`, `list-note-paragraphs`, `get-paragraph-link`, `get-note-structure`, `list-note-links`, `export-notes-markdown`, `export-notes-html`, `get-audio-transcripts`, `list-special-notes`, `list-native-tags`, `list-recent-notes`, `list-folder-tree`, `get-note-link`, the checklist annotations in `get-note-markdown`, `list-attachments` with `includePaths` or `firstImage`, `export-attachments`, `list-paper-attachments`, `export-paper-image`, and the database half of `get-sync-status`.
+Several tools read directly from the Apple Notes SQLite database, which lives in a macOS-protected directory. Those tools require **Full Disk Access** for the process running the MCP server: `query-notes`, `get-native-objects`, `get-note-tables`, `list-smart-folders`, `delete-folder-by-id`, `get-note-drawings`, `transcribe-note-audio`, `native-note-state`, `get-checklist-state`, `get-note-metadata`, `get-note-blocks`, `list-note-paragraphs`, `get-paragraph-link`, `get-note-structure`, `list-note-links`, `export-notes-markdown`, `export-notes-html`, `get-audio-transcripts`, `list-special-notes`, `list-native-tags`, `list-recent-notes`, `list-folder-tree`, `get-note-link`, the checklist annotations in `get-note-markdown`, `list-attachments` with `includePaths` or `firstImage`, `export-attachments`, `list-paper-attachments`, `export-paper-image`, and the database half of `get-sync-status`.
 
 > 📘 **For the full why-and-how walkthrough (which app to grant, verifying with `doctor`, graceful degradation), see the [Full Disk Access Setup Guide](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/FULL-DISK-ACCESS.md).** The summary below is the quick version.
 
@@ -2723,6 +2811,8 @@ Several tools read directly from the Apple Notes SQLite database, which lives in
 
 Every tool that does not read the Notes database works normally without Full Disk Access — that is the whole AppleScript surface (create, read, search, update, move, delete, folders, accounts, attachments, stats, export). The database-backed tools degrade like this:
 - `get-checklist-state` returns an error explaining that database access is needed
+- `query-notes` returns the same kind of error; use `search-notes` instead
+- `delete-folder-by-id` refuses to delete anything (it fails closed)
 - `get-note-metadata` returns the same kind of error — it has no non-database path
 - `list-special-notes` and the `list-native-tags` inventory return the same kind of error
 - `list-recent-notes` and `list-folder-tree` return the same kind of error
@@ -2750,7 +2840,7 @@ The helper never opens the Notes database and never writes under the Notes group
 
 ## Security and Privacy
 
-- **Local only** - All operations happen locally via AppleScript. No data is sent to external servers.
+- **Local only** - All operations happen locally, through AppleScript, the packaged Shortcuts, read-only reads of the Notes database, and helpers you build on your own Mac. The server makes no network requests, and `transcribe-note-audio` uses on-device speech recognition only. Whatever your MCP client does with the results is governed by that client.
 - **Permission required** - macOS will prompt for automation permission on first use.
 - **Password-protected notes** - Notes with passwords cannot be read or modified via this server.
 - **No credential storage** - The server doesn't store any passwords or authentication tokens.
@@ -2763,15 +2853,15 @@ The helper never opens the Notes database and never writes under the Notes group
 |------------|--------|
 | macOS only | Apple Notes and AppleScript are macOS-specific |
 | Batch ops run per-note | `batch-delete-notes` / `batch-move-notes` apply each note individually rather than as one bulk operation — AppleScript has no bulk equivalent to IMAP's `UID STORE`/`MOVE`. This is deliberate: it preserves per-note success/failure reporting. ([#26](https://github.com/sweetrb/apple-notes-mcp/issues/26)) |
-| Pinned notes are read-only | AppleScript exposes no `pinned` property. Pin state is readable via the BETA `get-note-metadata` tool (NoteStore database, needs Full Disk Access) but cannot be set ([#28](https://github.com/sweetrb/apple-notes-mcp/issues/28)) |
+| Pinning needs a Shortcut | AppleScript exposes no `pinned` property. Pin state is readable via the BETA `get-note-metadata` tool (NoteStore database, needs Full Disk Access), and [`set-note-pinned`](#set-note-pinned) sets it through the Background Operations Shortcut rather than AppleScript ([#28](https://github.com/sweetrb/apple-notes-mcp/issues/28)) |
 | Limited rich formatting | Use `format: "html"` on create/update for headings, lists, bold, code blocks; some complex formatting may not render |
-| Title matching | Most operations require exact title matches |
+| Exact IDs for writes | Writes take an exact note ID and a fresh `contentHash`, because Notes titles are not unique. Read tools that accept a `title` need an exact, case-sensitive match |
 | Checklist state | Requires [Full Disk Access](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/FULL-DISK-ACCESS.md) to read done/undone state from the database |
-| Checklist **creation** | Not supported. AppleScript's `body of note` setter strips `<input type="checkbox">` and ignores any checklist-styling CSS class. Apple Notes stores checklist items as a protobuf paragraph style (`style_type=103`) that AppleScript doesn't expose, and the SQLite database is read-only. See [Creating Checklists](#creating-checklists) below for the workaround. |
+| Checklist **creation** | Not possible through AppleScript: its `body of note` setter strips `<input type="checkbox">` and ignores any checklist-styling CSS class, because Notes stores checklist items as a protobuf paragraph style (`style_type=103`). The server creates real checklist items through Shortcuts instead; see [Creating Checklists](#creating-checklists). Checking or unchecking an existing item is not supported. |
 
 ### Creating Checklists
 
-**There is no programmatic way to create a true Apple Notes checklist via AppleScript** — and therefore no way via this MCP server. This is an Apple limitation, not a bug.
+**There is no programmatic way to create a true Apple Notes checklist via AppleScript.** This is an Apple limitation, not a bug. Plaintext and HTML writes therefore cannot produce checklists, so this server creates them through Apple Shortcuts instead (workaround 2 below).
 
 When a note is created or updated via AppleScript:
 
@@ -2786,7 +2876,7 @@ Apple Notes stores checklists as a paragraph style (`style_type=103`) inside a g
 **Workarounds:**
 
 1. **Create the note with bulleted list items, then convert manually in Notes.app.** Select the items and press <kbd>⇧⌘L</kbd> (or **Format → Checklist**). This converts the list in place and the resulting checklist will be readable by `get-checklist-state` and annotated by `get-note-markdown`.
-2. **Use the Apple Shortcuts app** to script the checklist creation, since Shortcuts can manipulate Notes content at a higher level than AppleScript. This server does that for you in two ways: [`create-checklist-item`](#create-checklist-item) appends one unchecked item to an existing note, and [`create-note`](#create-note) with `format: "markdown"` turns `- [ ]` / `- [x]` lines into checklist items with that done state through Notes' own Markdown importer, (see [Markdown notes](#markdown-notes)).
+2. **Use the Apple Shortcuts app** to script the checklist creation, since Shortcuts can manipulate Notes content at a higher level than AppleScript. This server does that for you in two ways: [`create-checklist-item`](#create-checklist-item) and [`create-checklist-items`](#create-checklist-items) append unchecked items to an existing note, and [`create-note`](#create-note) with `format: "markdown"` turns `- [ ]` / `- [x]` lines into checklist items with that done state through Notes' own Markdown importer (see [Markdown notes](#markdown-notes)).
 3. **Read-only checklist support is fully implemented** — once a checklist exists (created manually or by another app), `get-checklist-state` and `get-note-markdown` will read its done/undone state correctly (with Full Disk Access).
 
 If you need to *track* todos programmatically and don't strictly need them rendered as Apple Notes checklist UI, plain markdown-style `- [ ] item` / `- [x] item` lines in a `plaintext` note are a reasonable alternative — they are searchable, human-readable, and can be parsed by downstream tooling.

package/build/index.js

@@ -59329,7 +59329,7 @@ ${lines}${footer}`,
 registerTool(
   "get-note-content",
   {
-    description: "Use when: reading the full body text of one known note, by id (preferred) or title.\nReturns: the exact note id, content, contentHash revision token, parsed hashtags, nativeTags, restored links, richContentComplete/writable, and strippedImages/truncated when the body was capped. Read the warning when writable is false.\nDo not use when: you only need metadata (get-note-details) or Markdown with checklist state (get-note-markdown).\nNote: password-protected notes must be unlocked in Notes.app first.\nSafety: inline images larger than APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES (default 256 KB) are replaced with '[inline image omitted: ...]' text placeholders, so the returned body is lossy whenever truncated is true. Mutations refuse attachment-bearing notes; edit those in Notes.app. Notes.app returns images inside the body as base64, so a note with a very large image can time out; the error then names the cause, and a larger timeoutSeconds gives the read more time.",
+    description: "Use when: reading the full body text of one known note, by id (preferred) or title.\nReturns: the exact note id, content, contentHash revision token, parsed hashtags, nativeTags, restored links, richContentComplete/writable, and strippedImages/truncated when the body was capped. Read the warning when writable is false.\nDo not use when: you only need metadata (get-note-details) or Markdown with checklist state (get-note-markdown).\nNote: password-protected notes must be unlocked in Notes.app first.\nSafety: inline images larger than APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES (default 256 KB) are replaced with '[inline image omitted: ...]' text placeholders, so the returned body is lossy whenever truncated is true. For an attachment-bearing note, update-note refuses a full-body replacement; append-to-note with scopeText appends natively at the end and leaves attachments in place; add-attachment adds a file; move-note and delete-note work as usual. Make any other edit in Notes.app. Notes.app returns images inside the body as base64, so a note with a very large image can time out; the error then names the cause, and a larger timeoutSeconds gives the read more time.",
     inputSchema: {
       id: looseNoteId(external_exports.string()).optional().describe(`Note ID (preferred - more reliable than title): ${NOTE_ID_FORMS}`),
       title: external_exports.string().max(MAX.TITLE).optional().describe("Note title (use id instead when available)"),

package/docs/APPLESCRIPT-LIMITATIONS.md

@@ -19,7 +19,7 @@ shared, body, id, name, plaintext
 
 ## Pinned notes (#28)
 
-**Status: not feasible via AppleScript; readable via the NoteStore database.**
+**Status: not feasible via AppleScript; read from the NoteStore database and set through a Shortcut.**
 The Notes UI lets you pin a note to the top of a folder, but the `note` class
 has no `pinned` property. Asking for it raises error `-1700`:
 
@@ -33,7 +33,7 @@ end tell
 There is no alternative property, element, or command (`pin`, `pinned`,
 `favorite`, …) in the dictionary. Pinned state lives only in Notes' private
 Core Data store (`NoteStore.sqlite`), which is not part of the scriptable
-surface, and there is no supported way to *set* it at all.
+surface, and AppleScript offers no way to _set_ it.
 
 Reading it, however, did turn out to be worth doing. Since 2.5.0 the BETA
 `get-note-metadata` tool queries `ZISPINNED` on `ZICCLOUDSYNCINGOBJECT` in that
@@ -43,14 +43,17 @@ changes across macOS releases. It requires
 [Full Disk Access](./FULL-DISK-ACCESS.md) and is marked BETA precisely because
 the schema is version-dependent.
 
-**Conclusion:** pin state is **readable** (BETA, from the NoteStore database,
-Full Disk Access required) but **not settable** — and setting will not be added
-while Notes lacks a scriptable property. If a future macOS exposes one, revisit
-by re-running the probe above.
+**Conclusion:** pin state is **not scriptable** through AppleScript in either
+direction. It is **readable** (BETA, from the NoteStore database, Full Disk
+Access required) and, since the native background operations were added,
+**settable** through the packaged Background Operations Shortcut by
+`set-note-pinned`, which checks the expected current state and the note
+revision first. If a future macOS exposes a scriptable property, revisit by
+re-running the probe above.
 
 ## Note-to-note links (#30)
 
-**Status: link *relationships* are not exposed; a shareable deep link is.**
+**Status: link _relationships_ are not exposed to AppleScript; the server reads them from the database and inserts links by other routes.**
 Apple Notes lets you insert a link from one note to another in the UI, but
 AppleScript exposes no property or element for that relationship:
 
@@ -58,7 +61,7 @@ AppleScript exposes no property or element for that relationship:
   (undefined). There is no element that enumerates outgoing/incoming links.
 - Nothing in the dictionary inserts a link into a note's body.
 
-A shareable deep link to a note *is* available, and has been since 2.6.0:
+A shareable deep link to a note _is_ available, and has been since 2.6.0:
 `get-note-link` returns a `notes://showNote?identifier=<uuid>` URL that opens
 the note in Notes.app on macOS and iOS.
 
@@ -84,31 +87,39 @@ It **is** wrapped, as `show-note`, `show-folder`, `show-account`, and
 something useful on a machine with an active desktop session; to read a note's
 content, use `get-note-content` / `get-note-markdown` instead.
 
-**Conclusion:** link relationships between notes cannot be read, so a "list
-links in this note" feature is not possible, and links cannot be inserted into a
-body. To hand a note to a person or another app, use `get-note-link`; to address
-a note in a follow-up tool call, use the `id` returned by every read tool.
+**Conclusion:** AppleScript can neither read link relationships between notes
+nor insert a link into a body. The server does both by other routes:
+`list-note-links` reads a note's or folder's links from the NoteStore database
+(Full Disk Access required), `insert-link` appends a web, mail or Notes link,
+and `insert-note-link` appends another note's real deep link through the
+Background Operations Shortcut. To hand a note to a person or another app, use
+`get-note-link`; to address a note in a follow-up tool call, use the `id`
+returned by every read tool.
 
 ## Tags / hashtags (#29)
 
-**Status: parsed from the body, not first-class.** Apple Notes "tags" are inline
-`#hashtag` tokens you type into a note's text. They are **not** a scriptable
-property — the `note` class exposes no `tags` element, and the tag relationship
-lives only in Notes' private Core Data store. So the only way to surface a
-note's tags via AppleScript is to read them back out of the body text.
-
-This server does that: `get-note-content` parses the body and returns the tags
-as `hashtags` in its `structuredContent` (see `src/utils/hashtags.ts`). The
-rules match Notes' own behaviour — a token is `#` followed by letters/digits/
-underscores containing **at least one letter**, so `#123` is not a tag; tokens
-are de-duplicated case-insensitively.
+**Status: not scriptable; native tags go through Shortcuts.** A native Apple
+Notes tag is an inline tag attachment backed by an `ICHashtag` object in Notes'
+private Core Data store. It is **not** a scriptable property — the `note` class
+exposes no `tags` element — and `#word` text written through AppleScript stays
+plain text: Notes does not convert it into a native tag.
+
+This server therefore separates two things. `get-note-content` parses textual
+`#hashtag` tokens out of the body and returns them as `hashtags` (see
+`src/utils/hashtags.ts`); the rules match Notes' own — `#` followed by
+letters/digits/underscores containing **at least one letter**, so `#123` is not
+a tag; tokens are de-duplicated case-insensitively. Actual native tags are read
+from the database (`nativeTags`, `list-native-tags`, Full Disk Access) and
+written with `add-native-tags` / `remove-native-tags` / `replace-native-tag`,
+which drive the Notes Shortcuts action. A textual `hashtags` entry is not proof
+that Notes registered a native tag.
 
 Two related caveats:
 
 - The `tags` parameter on `create-note` is an application-level pass-through. It
   is stored on the returned object but Notes does **not** persist it, and it does
-  **not** create real `#hashtags` in the body. To make a real tag, put `#tag`
-  in the note content.
+  **not** create tags. Typing `#tag` into the content does not either; use
+  `add-native-tags` on the created note.
 - **Smart folders are not scriptable.** Notes' tag-driven Smart Folders cannot be
   created, read, or enumerated via AppleScript; there is no `smart folder` class
   in the dictionary. Only regular folders are scriptable.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "apple-notes-mcp",
-  "version": "2.9.20",
-  "description": "MCP server for Apple Notes - create, search, update, and manage notes via Claude and other AI assistants",
+  "version": "2.9.22",
+  "description": "MCP server for Apple Notes - read, search, create, edit, organize, and export notes on macOS via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -25,7 +25,16 @@
     "applescript",
     "macos",
     "notes",
-    "model-context-protocol"
+    "model-context-protocol",
+    "mcp-server",
+    "apple",
+    "notes-app",
+    "claude-code",
+    "claude-desktop",
+    "shortcuts",
+    "markdown",
+    "note-taking",
+    "icloud"
   ],
   "author": "Rob Sweet <rob@superiortech.io>",
   "license": "MIT",