apple-notes-mcp 2.8.15 → 2.8.16

package/README.md

@@ -59,22 +59,30 @@ This method also installs a **skill** that teaches Claude when and how to use Ap
 On the first tool call, macOS shows an Automation permission prompt ("Claude" wants access to control "Notes") — click **OK**. Optionally, grant **Full Disk Access** to the app that launches the server to enable the database-backed tools (`get-checklist-state`, `get-note-metadata`, `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.
 
 Native tag, checklist, table, pin, and rich append operations use two packaged
-Apple Shortcuts. Run the explicit setup once:
+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:
 
 ```bash
 npx -y apple-notes-mcp setup
 ```
 
 The command checks existing installations and opens only missing signed
-workflows. Confirm **Add Shortcut** in each macOS window, then verify with
-`npx -y apple-notes-mcp setup --check` or the MCP `doctor` tool. macOS does not
+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
-bridge — `Apple Notes MCP - Native Tags` and
-`Apple Notes MCP - Background Operations v5` — once in the foreground, choosing
-**Always Allow** when Shortcuts asks for permission. The server runs these
+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`](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
@@ -202,10 +210,10 @@ 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 | Yes | The body content of the note (do not repeat the title here) |
-| `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) |
+| `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"` |
 | `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). 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) or `"html"`. In both formats, the title is automatically prepended as `<h1>`. In plaintext mode, newlines become `<br>`, tabs become `<br>`, and backslashes are preserved as HTML entities |
+| `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) |
 
 **Example (tagged with inline hashtags):**
 ```json
@@ -235,13 +243,63 @@ Creates a new note in Apple Notes.
 
 > **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:** `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](https://github.com/sweetrb/apple-notes-mcp/issues/172)). Real
-> Heading/Subheading styles can currently only be added to a note that already
-> exists, with [`append-native`](#append-native)'s `format: "markdown"`.
+> **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](https://github.com/sweetrb/apple-notes-mcp/issues/172)). Use
+> `format: "markdown"` for real headings in a new note, or
+> [`append-native`](#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.
+
+```json
+{
+  "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`](#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 `&amp;`, `---` or
+  `===` lines, 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.
+- 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`](shortcuts/README.md).
 
 **Returns:** Confirmation message with note title and ID. Save the ID for subsequent operations like `update-note`, `delete-note`, etc.
 
@@ -1073,9 +1131,11 @@ Install the signed workflows once as described in
 foreground in Shortcuts.app and choose **Always Allow** — again after every
 upgrade — so no first-run consent prompt is left for a background run that
 cannot display it. Native writes never use UI
-automation or write directly to the Notes database. Every operation requires an
-exact note ID, a fresh `expectedContentHash`, and a distinctive existing
-`scopeText` so the Shortcut and server can independently resolve the same note.
+automation or write directly to the Notes database. Every operation on an
+existing note requires an exact note ID, a fresh `expectedContentHash`, and a
+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"`.
 
 #### `get-capabilities`
 
@@ -1095,7 +1155,10 @@ subset as `format: "html"`'s Markdown-shaped content (`#`/`##`/`###` headings,
 flat lists, emphasis, and inline links) but is sent through Notes' own native
 Markdown importer rather than converted to HTML first, so `#`/`##`/`###`
 produce real Title/Heading/Subheading — Notes' HTML importer only
-distinguishes two heading levels and renders `###` the same as `##`. A
+distinguishes two heading levels and renders `###` the same as `##`. Markdown
+that the importer would rewrite, so the appended text could not be verified, is
+refused before anything is written; the list is under
+[Markdown notes](#markdown-notes). A
 transport failure names the Shortcut it was waiting on, so a missing or
 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
@@ -1417,7 +1480,7 @@ In a JSON string literal the two characters `\\` denote **one** literal backslas
 ### Native writes time out or report an uncertain outcome
 - Symptom: `add-native-tags`, `set-note-pinned`, `append-native` or another native write fails with "Shortcuts timed out waiting for …", "Operation outcome uncertain" or "readback was not verified", while `doctor` and `get-capabilities` report the bridges installed
 - Common cause, especially right after install or upgrade: the bridge Shortcut is waiting on a first-run consent prompt. The server runs it in the background, where Shortcuts cannot display that prompt, so the run stalls until it times out
-- Fix: open Shortcuts.app, run the Shortcut the error names (`Apple Notes MCP - Native Tags` or `Apple Notes MCP - Background Operations v5`) once in the foreground and choose **Always Allow**. Each bridge needs this once; quitting or relaunching Shortcuts.app or Notes.app does not clear it
+- Fix: open Shortcuts.app, run the Shortcut the error names (`Apple Notes MCP - Native Tags`, `Apple Notes MCP - Background Operations v5` or `Apple Notes MCP - Create Markdown Note`) once in the foreground and choose **Always Allow**. Each bridge needs this once; quitting or relaunching Shortcuts.app or Notes.app does not clear it
 - Read the exact note before retrying — the write may have landed
 
 ### "Note not found"

package/build/index.js

@@ -42923,6 +42923,8 @@ function comparableVisibleText(html) {
 var BACKGROUND_SHORTCUT = "Apple Notes MCP - Background Operations v5";
 var backgroundStatus = () => nativeTagsStatus(process.env.APPLE_NOTES_MCP_BACKGROUND_SHORTCUT || BACKGROUND_SHORTCUT);
 var nativeTagBridgeStatus = () => nativeTagsStatus();
+var MARKDOWN_NOTE_SHORTCUT = "Apple Notes MCP - Create Markdown Note";
+var markdownNoteStatus = () => nativeTagsStatus(process.env.APPLE_NOTES_MCP_MARKDOWN_SHORTCUT || MARKDOWN_NOTE_SHORTCUT);
 function readBackgroundSnapshot(manager, id2) {
   if (!/^x-coredata:\/\/[0-9a-f-]+\/ICNote\/p\d+$/i.test(id2))
     throw new Error("Exact note ID required");
@@ -42974,6 +42976,17 @@ var NATIVE_APPEND_ELEMENTS = [
 ];
 var NATIVE_APPEND_SPAN_STYLE = /^font-size\s*:\s*\d{1,3}(?:\.\d+)?(?:px|pt)\s*;?$/i;
 var NATIVE_APPEND_HTML_SUBSET = `Native append accepts ${NATIVE_APPEND_ELEMENTS.map((e) => `<${e}>`).join(" ")}, with href on <a> and a font-size style on <span> as the only attributes; everything else needs update-note.`;
+var UNDERSCORES_OUTSIDE_A_WORD = "underscores outside a word";
+var UNMODELED_MARKDOWN = [
+  [/(?<![\p{L}\p{N}])_|_(?![\p{L}\p{N}])/mu, UNDERSCORES_OUTSIDE_A_WORD],
+  [/\\[!-/:-@[-`{-~]/m, "backslash escapes"],
+  [/&(?:#\d+|#x[0-9a-f]+|[a-z][a-z0-9]*);/im, "character references"],
+  [/^ {0,3}(?:=+|-+|(?:\*[ \t]*){3,})[ \t]*$/m, "underline or rule lines"],
+  [/^ {1,3}(?:#|[-+*][ \t]|\d+[.)][ \t])/m, "indented headings or list items"],
+  [/^\d+\)[ \t]/m, "`1)` lists"],
+  [/^#{1,3}[ \t].*[ \t]#+[ \t]*$/m, "closing # sequences"],
+  [/\[[^\]\n]*[*_][^\]\n]*\]\(/m, "formatting inside link labels"]
+];
 function validateAppendContent(content, format) {
   if (!content || content.length > 1024 * 1024 || content.includes("\0"))
     throw new Error("Invalid append content (limit 1 MiB)");
@@ -43003,11 +43016,18 @@ function validateAppendContent(content, format) {
     }
     if (/<!--|<!|<\?|<[^>]*$/u.test(content)) throw new Error("Unsupported HTML markup");
   }
-  if (format === "markdown" && /!\[|<\/?[a-z]|\]\(\s*(?:javascript|data|file):/i.test(content))
-    throw new Error("Markdown images, raw HTML and local/executable links are unsupported");
+  if (format === "markdown") {
+    if (/!\[|<\/?[a-z]|\]\(\s*(?:javascript|data|file):/i.test(content))
+      throw new Error("Markdown images, raw HTML and local/executable links are unsupported");
+    const withoutLinkDestinations = content.replace(/(\[[^\]\n]+\])\([^()\s]+\)/g, "$1()");
+    for (const [pattern, name] of UNMODELED_MARKDOWN)
+      if (pattern.test(name === UNDERSCORES_OUTSIDE_A_WORD ? withoutLinkDestinations : content))
+        throw new Error(
+          `Markdown cannot use ${name}; Notes would change that text, so the result could not be verified`
+        );
+  }
 }
-function runBackgroundShortcut(input) {
-  const status = backgroundStatus();
+function runBackgroundShortcut(input, status = backgroundStatus()) {
   if (!status.installed)
     throw new Error(
       `Install the supplied "${status.shortcut}" Shortcut once; Shortcuts must list it exactly once`
@@ -43109,6 +43129,11 @@ function assertPreserved(before, after, options = {}) {
       }
   }
 }
+function describeTransportFailure(error2) {
+  const detail = error2;
+  const named = detail?.shortcut ? `the "${detail.shortcut}" Shortcut` : "the background Shortcut";
+  return detail?.code === "ETIMEDOUT" ? `Shortcuts timed out waiting for ${named}. ${shortcutConsentHint(detail.shortcut)}` : `${named} failed: ${String(detail?.stderr || detail?.message || "no output").trim().slice(0, 400)}`;
+}
 function mutateBackground(request, operation, data, verify, deps) {
   if (request.scopeText.length < 12 || request.scopeText.length > 500 || /[\r\n\0]/u.test(request.scopeText))
     throw new Error("Use a distinctive existing single-line scope of 12\u2013500 characters");
@@ -43128,9 +43153,7 @@ function mutateBackground(request, operation, data, verify, deps) {
     deps.run({ ...data, operation, title: before.title, scopeText: request.scopeText });
   } catch (error2) {
     transportUncertain = true;
-    const detail = error2;
-    const named = detail?.shortcut ? `the "${detail.shortcut}" Shortcut` : "the background Shortcut";
-    transportMessage = detail?.code === "ETIMEDOUT" ? `Shortcuts timed out waiting for ${named}. ${shortcutConsentHint(detail.shortcut)}` : `${named} failed: ${String(detail?.stderr || detail?.message || "no output").trim().slice(0, 400)}`;
+    transportMessage = describeTransportFailure(error2);
   }
   const after = deps.read(request.id);
   try {
@@ -43218,6 +43241,109 @@ function setNativeTag(manager, request) {
     deps
   );
 }
+var literalMarkdown = (text) => text.replace(/[!-/:-@[-`{-~]/g, "\\$&");
+function headingLevels(html) {
+  return [...html.matchAll(/<h([1-3])\b[^>]*>([\s\S]*?)<\/h\1>/gi)].filter((match) => comparableVisibleText(match[2])).map((match) => Number(match[1]));
+}
+function createMarkdownNote(manager, request, run = runBackgroundShortcut) {
+  if (/[\r\n\0]/u.test(request.title)) throw new Error("A Markdown note title must be one line");
+  validateAppendContent(request.content, "markdown");
+  const bodyHtml = appendMarkdownHtml(request.content);
+  if (request.folder) buildFolderReference(request.folder);
+  const expectedText = `${request.title} ${comparableVisibleText(bodyHtml)}`.replace(/\s+/gu, " ").trim();
+  const expectedLevels = [1, ...headingLevels(bodyHtml)].join();
+  const status = markdownNoteStatus();
+  if (!status.installed)
+    throw new Error(
+      `Install the supplied "${status.shortcut}" Shortcut once; Shortcuts must list it exactly once`
+    );
+  const segments = (path4) => JSON.stringify(splitFolderPath(path4).map((part) => part.toLocaleLowerCase()));
+  if (request.folder) {
+    const wanted = segments(request.folder);
+    if (!manager.listAccounts().some(
+      (account) => account.defaultFolder && manager.listFolders(account.name).some((folder) => segments(folder.name) === wanted)
+    ))
+      throw new Error(
+        `Folder "${request.folder}" does not exist; create it with create-folder first. Nothing was created`
+      );
+  }
+  const defaultFolderNotes = () => new Map(
+    manager.listAccounts().flatMap(
+      (account) => account.defaultFolder ? manager.listNoteRefs(account.name, account.defaultFolder).map((note) => [note.id, account.name]) : []
+    )
+  );
+  const before = defaultFolderNotes();
+  let transportMessage = "";
+  try {
+    run(
+      {
+        operation: "create-markdown",
+        text: `# ${literalMarkdown(request.title)}
+
+${request.content}`
+      },
+      status
+    );
+  } catch (error2) {
+    transportMessage = describeTransportFailure(error2);
+  }
+  const reason = (error2) => error2 instanceof Error ? error2.message : String(error2);
+  let candidates = [];
+  try {
+    const created = [...defaultFolderNotes()].filter(([noteId3]) => !before.has(noteId3));
+    candidates = created.map(([noteId3]) => noteId3);
+    const failures = [];
+    const verified = created.flatMap(([noteId3, account2]) => {
+      try {
+        const note2 = readBackgroundSnapshot(manager, noteId3);
+        if (note2.rich.text.replace(/[\s\ufffc]+/gu, " ").trim() !== expectedText)
+          throw new Error("Note text not verified");
+        if (headingLevels(note2.html).join() !== expectedLevels)
+          throw new Error("Heading styles not verified");
+        assertAppendedHtmlLinks(0, note2.rich.links, bodyHtml);
+        return [{ id: noteId3, account: account2, note: note2 }];
+      } catch (error2) {
+        failures.push(`${noteId3}: ${reason(error2)}`);
+        return [];
+      }
+    });
+    if (verified.length !== 1)
+      throw new Error(
+        verified.length ? `${verified.length} matching notes appeared (${verified.map((v) => v.id).join(", ")})` : created.length ? `no new note verified (${failures.join("; ")})` : "no new note was found in the default folder"
+      );
+    const { id: id2, account } = verified[0];
+    candidates = [id2];
+    let { note } = verified[0];
+    if (request.folder) {
+      const wanted = segments(request.folder);
+      if (!manager.listFolders(account).some((folder) => segments(folder.name) === wanted))
+        throw new Error(
+          `created and verified in the ${account} default folder, but folder "${request.folder}" does not exist in ${account}; create it there, then use move-note with id ${id2} instead of creating the note again`
+        );
+      if (!manager.moveNoteById(id2, request.folder, account))
+        throw new Error(
+          `created and verified in the ${account} default folder, but not moved to "${request.folder}"; use move-note instead of creating it again`
+        );
+      note = readBackgroundSnapshot(manager, id2);
+    }
+    return {
+      ok: true,
+      id: id2,
+      title: request.title,
+      folder: request.folder,
+      account,
+      contentHash: note.hash,
+      verified: true,
+      ...transportMessage ? {
+        transportWarning: "Transport was uncertain; exact-ID readback verified the requested result"
+      } : {}
+    };
+  } catch (error2) {
+    throw new Error(
+      `Operation outcome uncertain; ${candidates.length ? `read ${candidates.length === 1 ? "note" : "notes"} ${candidates.join(", ")}` : "search for the title"} before any retry: ${reason(error2)}${transportMessage ? `; ${transportMessage}` : ""}`
+    );
+  }
+}
 
 // src/tools/doctor.ts
 function runDoctor(manager) {
@@ -43256,10 +43382,11 @@ function runDoctor(manager) {
       (name) => nativeTagsStatus(name)
     );
     const missing = bridgeStatuses.filter((status) => !status.installed);
+    const markdown = markdownBridgeDetail();
     checks.push({
       name: "Native write Shortcuts",
       status: missing.length ? "warn" : "ok",
-      detail: missing.length ? `missing: ${missing.map((status) => status.shortcut).join(", ")}. Run apple-notes-mcp setup and approve Add Shortcut in macOS. ${consentReminder}` : `both native-write bridges are installed. ${consentReminder}`
+      detail: missing.length ? `missing: ${missing.map((status) => status.shortcut).join(", ")}. Run apple-notes-mcp setup and approve Add Shortcut in macOS. ${markdown} ${consentReminder}` : `both native-write bridges are installed. ${markdown} ${consentReminder}`
     });
   } catch (error2) {
     checks.push({
@@ -43272,6 +43399,14 @@ function runDoctor(manager) {
   const healthy = !checks.some((c) => c.status === "fail");
   return { healthy, checks };
 }
+function markdownBridgeDetail() {
+  const purpose = 'needed only for create-note format: "markdown" on macOS 26+';
+  try {
+    return nativeTagsStatus(MARKDOWN_NOTE_SHORTCUT).installed ? `Optional ${MARKDOWN_NOTE_SHORTCUT} bridge: installed (${purpose}).` : `Optional ${MARKDOWN_NOTE_SHORTCUT} bridge: not installed (${purpose}; apple-notes-mcp setup offers it).`;
+  } catch (error2) {
+    return `Optional ${MARKDOWN_NOTE_SHORTCUT} bridge: could not inspect (${purpose}): ${String(error2)}.`;
+  }
+}
 function checkNodeRuntimeSignature() {
   const name = "Node runtime signature";
   try {
@@ -43894,7 +44029,8 @@ var VERIFIED_BACKGROUND = /* @__PURE__ */ new Set([
   "insert-note-link",
   "set-note-pinned",
   "remove-native-tags",
-  "replace-native-tag"
+  "replace-native-tag",
+  "create-note-markdown"
 ]);
 var LIVE_VALIDATION_BLOCKERS = {};
 var signingRefusal = "Installed Shortcuts refuses to sign this Notes action (unsupported features); no background fallback is enabled";
@@ -43982,16 +44118,24 @@ function registerNativeOperations(server2, manager) {
         "set-note-pinned",
         "remove-native-tags",
         "replace-native-tag",
-        "insert-note-link"
+        "insert-note-link",
+        "create-note-markdown"
       ];
       let tagBridgeInstalled = false;
       try {
         tagBridgeInstalled = nativeTagBridgeStatus().installed;
       } catch {
       }
+      let markdownBridgeInstalled = false;
+      try {
+        markdownBridgeInstalled = markdownNoteStatus().installed;
+      } catch {
+      }
+      const installed = (name) => name === "create-note-markdown" ? markdownBridgeInstalled : bridge.installed;
       return {
         bridge,
         nativeTagBridgeInstalled: tagBridgeInstalled,
+        markdownNoteBridgeInstalled: markdownBridgeInstalled,
         mode: "background-only",
         operations: Object.fromEntries(
           native.map((name) => [
@@ -43999,8 +44143,8 @@ function registerNativeOperations(server2, manager) {
             {
               implemented: true,
               verified: VERIFIED_BACKGROUND.has(name),
-              available: VERIFIED_BACKGROUND.has(name) && (!native.includes(name) || bridge.installed) && (name !== "replace-native-tag" || tagBridgeInstalled),
-              reason: !VERIFIED_BACKGROUND.has(name) ? UNAVAILABLE[name] || LIVE_VALIDATION_BLOCKERS[name] || "Live validation pending; install the shortcut and complete the isolated acceptance tests" : native.includes(name) && !bridge.installed ? "Run apple-notes-mcp setup and approve Add Shortcut in macOS" : name === "replace-native-tag" && !tagBridgeInstalled ? "Run apple-notes-mcp setup to install the Native Tags bridge for the addition phase" : void 0
+              available: VERIFIED_BACKGROUND.has(name) && installed(name) && (name !== "replace-native-tag" || tagBridgeInstalled),
+              reason: !VERIFIED_BACKGROUND.has(name) ? UNAVAILABLE[name] || LIVE_VALIDATION_BLOCKERS[name] || "Live validation pending; install the shortcut and complete the isolated acceptance tests" : !installed(name) ? "Run apple-notes-mcp setup and approve Add Shortcut in macOS" : name === "replace-native-tag" && !tagBridgeInstalled ? "Run apple-notes-mcp setup to install the Native Tags bridge for the addition phase" : void 0
             }
           ])
         ),
@@ -44217,13 +44361,21 @@ function registerNativeOperations(server2, manager) {
 // src/setupShortcuts.ts
 import { spawnSync as spawnSync2 } from "node:child_process";
 import { existsSync as existsSync7 } from "node:fs";
+import { release } from "node:os";
 import { dirname as dirname2, resolve as resolve2 } from "node:path";
 import { fileURLToPath } from "node:url";
+var OPTIONAL_BRIDGE_NOTE = "(optional \u2014 needed only for create-note format: markdown, macOS 26+)";
+var MARKDOWN_MIN_DARWIN_MAJOR = 25;
 var shortcutFiles = [
   { name: NATIVE_TAGS_SHORTCUT, file: "Apple Notes MCP - Native Tags.shortcut" },
   {
     name: BACKGROUND_SHORTCUT,
     file: "Apple Notes MCP - Background Operations v5.shortcut"
+  },
+  {
+    name: MARKDOWN_NOTE_SHORTCUT,
+    file: "Apple Notes MCP - Create Markdown Note.shortcut",
+    optional: true
   }
 ];
 function setupShortcuts(checkOnly, dependencies = {}) {
@@ -44234,7 +44386,9 @@ function setupShortcuts(checkOnly, dependencies = {}) {
     return result.status === 0 ? { ok: true } : { ok: false, error: result.stderr || result.error?.message || "open failed" };
   });
   const baseDirectory = dependencies.baseDirectory || resolve2(dirname2(fileURLToPath(import.meta.url)), "../shortcuts");
-  const items = shortcutFiles.map(({ name, file }) => {
+  const osRelease = (dependencies.osRelease || release)();
+  const darwinMajor = Number.parseInt(osRelease.split(".")[0], 10);
+  const items = shortcutFiles.map(({ name, file, optional: optional2 }) => {
     const path4 = resolve2(baseDirectory, file);
     let installed = false;
     let identifier;
@@ -44247,27 +44401,41 @@ function setupShortcuts(checkOnly, dependencies = {}) {
       error2 = cause instanceof Error ? cause.message : String(cause);
     }
     let opened = false;
+    let skipped;
     if (!installed && !checkOnly) {
-      if (!exists(path4)) error2 = `Packaged Shortcut is missing: ${path4}`;
+      if (optional2 && !(darwinMajor >= MARKDOWN_MIN_DARWIN_MAJOR))
+        skipped = `requires macOS 26 or later (this Mac reports Darwin ${osRelease})`;
+      else if (!exists(path4)) error2 = `Packaged Shortcut is missing: ${path4}`;
       else {
         const result = open(path4);
         opened = result.ok;
         if (!result.ok) error2 = result.error || `Could not open ${file}`;
       }
     }
-    return { name, installed, identifier, file: path4, opened, ...error2 ? { error: error2 } : {} };
+    return {
+      name,
+      installed,
+      identifier,
+      file: path4,
+      opened,
+      ...optional2 ? { optional: optional2 } : {},
+      ...skipped ? { skipped } : {},
+      ...error2 ? { error: error2 } : {}
+    };
   });
-  return { ready: items.every((item) => item.installed), checkOnly, items };
+  return { ready: items.every((item) => item.optional || item.installed), checkOnly, items };
 }
 function formatShortcutSetup(report) {
   const lines = ["Apple Notes MCP Shortcut setup", ""];
   for (const item of report.items) {
-    if (item.installed) lines.push(`\u2713 ${item.name} (${item.identifier})`);
-    else if (item.opened) lines.push(`\u2192 ${item.name}: confirm \u201CAdd Shortcut\u201D in macOS`);
-    else lines.push(`\u2717 ${item.name}: ${item.error || "not installed"}`);
+    const note = item.optional ? ` ${OPTIONAL_BRIDGE_NOTE}` : "";
+    if (item.installed) lines.push(`\u2713 ${item.name} (${item.identifier})${note}`);
+    else if (item.opened) lines.push(`\u2192 ${item.name}: confirm \u201CAdd Shortcut\u201D in macOS${note}`);
+    else if (item.skipped) lines.push(`\u2013 ${item.name}: skipped, ${item.skipped}${note}`);
+    else lines.push(`\u2717 ${item.name}: ${item.error || "not installed"}${note}`);
   }
   lines.push("");
-  if (report.ready) lines.push("Both Shortcut bridges are installed.");
+  if (report.ready) lines.push("Both required Shortcut bridges are installed.");
   else if (report.checkOnly) lines.push("Run `apple-notes-mcp setup` to open missing workflows.");
   else
     lines.push(
@@ -44383,9 +44551,11 @@ registerTool(
       content: external_exports.string().min(1, "Content is required").max(MAX.CONTENT).describe(
         'Note body. AppleScript cannot create true Apple Notes checklists \u2014 `<input type="checkbox">`, checklist CSS classes, and markdown `- [ ]` lines do not render as checkable items. To produce a checklist, create the note with a plain `<ul>` or `- ` list and convert it in Notes.app with \u21E7\u2318L.'
       ),
-      format: external_exports.enum(["plaintext", "html"]).optional().default("plaintext").describe("Content format: 'plaintext' (default) or 'html' for rich formatting"),
+      format: external_exports.enum(["plaintext", "html", "markdown"]).optional().default("plaintext").describe(
+        "Content format: 'plaintext' (default), 'html' for rich formatting, or 'markdown' for real Title/Heading/Subheading styles through the Create Markdown Note Shortcut (iCloud only; see get-capabilities)"
+      ),
       tags: external_exports.array(external_exports.string().max(MAX.TAG)).max(MAX.TAGS).optional().describe(
-        "Returned-only metadata \u2014 NOT written to Notes.app. Apple Notes tags can't be set via AppleScript, so any values passed here are echoed back in the response but do not appear on the created note. Use #hashtags in the body for searchable text; this does not create native tag objects. Native tags need the Notes Shortcuts action."
+        "Returned-only metadata \u2014 NOT written to Notes.app. Apple Notes tags can't be set via AppleScript, so any values passed here are echoed back in the response but do not appear on the created note. Use #hashtags in the body for searchable text; this does not create native tag objects. Native tags need the Notes Shortcuts action. Refused with format 'markdown': add tags afterwards with add-native-tags."
       ),
       folder: external_exports.string().max(MAX.FOLDER).optional().describe(
         "Folder to create the note in (supports nested paths like 'Work/Clients'). The folder must already exist \u2014 this tool does not create it; call create-folder first, which is idempotent and creates intermediate segments."
@@ -44405,6 +44575,19 @@ registerTool(
     }
   },
   withErrorHandling(({ title, content, format = "plaintext", tags = [], folder, account }) => {
+    if (format === "markdown") {
+      if (account)
+        return errorResponse(
+          "Markdown notes are created in the iCloud account, the only one where Notes interprets Markdown; omit account"
+        );
+      if (tags.length)
+        return errorResponse(
+          'tags are not supported with format "markdown"; create the note without tags, then add them with add-native-tags using the returned id'
+        );
+      requireValidated("create-note-markdown");
+      const result = createMarkdownNote(notesManager, { title, content, folder });
+      return successResponse(`Note created from Markdown: "${title}" [id: ${result.id}]`, result);
+    }
     const note = notesManager.createNote(title, content, tags, folder, account, format);
     if (!note) {
       const target = folder ? ` Most often the folder "${folder}" does not exist: run list-folders to check, then create-folder to create it (it is idempotent and creates intermediate segments).` : account ? ` Most often the account "${account}" is not configured in Notes.app: run list-accounts to check the exact name.` : "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-notes-mcp",
-  "version": "2.8.15",
+  "version": "2.8.16",
   "description": "MCP server for Apple Notes - create, search, update, and manage notes via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",

package/shortcuts/Apple Notes MCP - Create Markdown Note.unsigned.shortcut

@@ -0,0 +1,394 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>WFWorkflowName</key>
+	<string>Apple Notes MCP - Create Markdown Note</string>
+	<key>WFWorkflowActions</key>
+	<array>
+		<dict>
+			<key>WFWorkflowActionIdentifier</key>
+			<string>is.workflow.actions.comment</string>
+			<key>WFWorkflowActionParameters</key>
+			<dict>
+				<key>UUID</key>
+				<string>9677FA88-6915-5FA3-A68B-56A5E5257DE6</string>
+				<key>WFCommentActionText</key>
+				<string>Creates one note from Markdown with Notes' own importer, in the iCloud default folder. Input: JSON {operation: create-markdown, text}. No search, edits, deletion, shell scripts, network or arbitrary action execution. The MCP finds the new note among notes added to the default folder and verifies it by exact-ID readback.</string>
+			</dict>
+		</dict>
+		<dict>
+			<key>WFWorkflowActionIdentifier</key>
+			<string>is.workflow.actions.detect.dictionary</string>
+			<key>WFWorkflowActionParameters</key>
+			<dict>
+				<key>UUID</key>
+				<string>C826AE0C-31B7-508F-8AA6-2C1627425D3B</string>
+				<key>WFInput</key>
+				<dict>
+					<key>Value</key>
+					<dict>
+						<key>Type</key>
+						<string>ExtensionInput</string>
+					</dict>
+					<key>WFSerializationType</key>
+					<string>WFTextTokenAttachment</string>
+				</dict>
+			</dict>
+		</dict>
+		<dict>
+			<key>WFWorkflowActionIdentifier</key>
+			<string>is.workflow.actions.getvalueforkey</string>
+			<key>WFWorkflowActionParameters</key>
+			<dict>
+				<key>UUID</key>
+				<string>D8DFFD6F-2EF2-5F63-8B77-9578929A96CD</string>
+				<key>WFInput</key>
+				<dict>
+					<key>Value</key>
+					<dict>
+						<key>Type</key>
+						<string>ActionOutput</string>
+						<key>OutputUUID</key>
+						<string>C826AE0C-31B7-508F-8AA6-2C1627425D3B</string>
+						<key>OutputName</key>
+						<string>request</string>
+					</dict>
+					<key>WFSerializationType</key>
+					<string>WFTextTokenAttachment</string>
+				</dict>
+				<key>WFDictionaryKey</key>
+				<string>operation</string>
+				<key>WFGetDictionaryValueType</key>
+				<string>Value</string>
+			</dict>
+		</dict>
+		<dict>
+			<key>WFWorkflowActionIdentifier</key>
+			<string>is.workflow.actions.gettext</string>
+			<key>WFWorkflowActionParameters</key>
+			<dict>
+				<key>UUID</key>
+				<string>BA3704CC-7103-5406-A7A9-4ACA96514A95</string>
+				<key>WFTextActionText</key>
+				<dict>
+					<key>WFSerializationType</key>
+					<string>WFTextTokenString</string>
+					<key>Value</key>
+					<dict>
+						<key>string</key>
+						<string></string>
+						<key>attachmentsByRange</key>
+						<dict>
+							<key>{0, 1}</key>
+							<dict>
+								<key>Type</key>
+								<string>ActionOutput</string>
+								<key>OutputUUID</key>
+								<string>D8DFFD6F-2EF2-5F63-8B77-9578929A96CD</string>
+								<key>OutputName</key>
+								<string>operation-value</string>
+							</dict>
+						</dict>
+					</dict>
+				</dict>
+			</dict>
+		</dict>
+		<dict>
+			<key>WFWorkflowActionIdentifier</key>
+			<string>is.workflow.actions.getvalueforkey</string>
+			<key>WFWorkflowActionParameters</key>
+			<dict>
+				<key>UUID</key>
+				<string>9EC8FFF3-7821-592E-86A4-BC712A669591</string>
+				<key>WFInput</key>
+				<dict>
+					<key>Value</key>
+					<dict>
+						<key>Type</key>
+						<string>ActionOutput</string>
+						<key>OutputUUID</key>
+						<string>C826AE0C-31B7-508F-8AA6-2C1627425D3B</string>
+						<key>OutputName</key>
+						<string>request</string>
+					</dict>
+					<key>WFSerializationType</key>
+					<string>WFTextTokenAttachment</string>
+				</dict>
+				<key>WFDictionaryKey</key>
+				<string>text</string>
+				<key>WFGetDictionaryValueType</key>
+				<string>Value</string>
+			</dict>
+		</dict>
+		<dict>
+			<key>WFWorkflowActionIdentifier</key>
+			<string>is.workflow.actions.gettext</string>
+			<key>WFWorkflowActionParameters</key>
+			<dict>
+				<key>UUID</key>
+				<string>68CEF93A-EBC3-5F0C-831D-B459A0AEA703</string>
+				<key>WFTextActionText</key>
+				<dict>
+					<key>WFSerializationType</key>
+					<string>WFTextTokenString</string>
+					<key>Value</key>
+					<dict>
+						<key>string</key>
+						<string></string>
+						<key>attachmentsByRange</key>
+						<dict>
+							<key>{0, 1}</key>
+							<dict>
+								<key>Type</key>
+								<string>ActionOutput</string>
+								<key>OutputUUID</key>
+								<string>9EC8FFF3-7821-592E-86A4-BC712A669591</string>
+								<key>OutputName</key>
+								<string>text-value</string>
+							</dict>
+						</dict>
+					</dict>
+				</dict>
+			</dict>
+		</dict>
+		<dict>
+			<key>WFWorkflowActionIdentifier</key>
+			<string>is.workflow.actions.conditional</string>
+			<key>WFWorkflowActionParameters</key>
+			<dict>
+				<key>UUID</key>
+				<string>C49370C1-C96A-567A-91A8-75AB9A8E9695</string>
+				<key>GroupingIdentifier</key>
+				<string>0DD3CC74-CF2E-5A9D-AE11-C1DC205557E8</string>
+				<key>WFControlFlowMode</key>
+				<integer>0</integer>
+				<key>WFInput</key>
+				<dict>
+					<key>Type</key>
+					<string>Variable</string>
+					<key>Variable</key>
+					<dict>
+						<key>Value</key>
+						<dict>
+							<key>Type</key>
+							<string>ActionOutput</string>
+							<key>OutputUUID</key>
+							<string>BA3704CC-7103-5406-A7A9-4ACA96514A95</string>
+							<key>OutputName</key>
+							<string>operation</string>
+						</dict>
+						<key>WFSerializationType</key>
+						<string>WFTextTokenAttachment</string>
+					</dict>
+				</dict>
+				<key>WFCondition</key>
+				<integer>4</integer>
+				<key>WFConditionalActionString</key>
+				<string>create-markdown</string>
+			</dict>
+		</dict>
+		<dict>
+			<key>WFWorkflowActionIdentifier</key>
+			<string>com.apple.mobilenotes.SharingExtension</string>
+			<key>WFWorkflowActionParameters</key>
+			<dict>
+				<key>UUID</key>
+				<string>ACE3922A-BF8C-5266-88EF-5492F1E16DD9</string>
+				<key>WFCreateNoteInput</key>
+				<dict>
+					<key>WFSerializationType</key>
+					<string>WFTextTokenString</string>
+					<key>Value</key>
+					<dict>
+						<key>string</key>
+						<string></string>
+						<key>attachmentsByRange</key>
+						<dict>
+							<key>{0, 1}</key>
+							<dict>
+								<key>Type</key>
+								<string>ActionOutput</string>
+								<key>OutputUUID</key>
+								<string>68CEF93A-EBC3-5F0C-831D-B459A0AEA703</string>
+								<key>OutputName</key>
+								<string>text</string>
+							</dict>
+						</dict>
+					</dict>
+				</dict>
+				<key>interpretAsMarkdown</key>
+				<true/>
+				<key>OpenWhenRun</key>
+				<false/>
+				<key>WFNoteGroup</key>
+				<dict>
+					<key>DisplayString</key>
+					<string>Notes</string>
+					<key>Identifier</key>
+					<string>applenotes:folder/DefaultFolder-CloudKit</string>
+				</dict>
+				<key>folder</key>
+				<dict>
+					<key>identifier</key>
+					<string>applenotes:folder/DefaultFolder-CloudKit</string>
+					<key>subtitle</key>
+					<dict>
+						<key>key</key>
+						<string>Notes</string>
+					</dict>
+					<key>symbol</key>
+					<dict>
+						<key>systemName</key>
+						<string>folder</string>
+					</dict>
+					<key>title</key>
+					<dict>
+						<key>key</key>
+						<string>Notes</string>
+					</dict>
+				</dict>
+				<key>AppIntentDescriptor</key>
+				<dict>
+					<key>AppIntentIdentifier</key>
+					<string>CreateNoteLinkAction</string>
+					<key>BundleIdentifier</key>
+					<string>com.apple.Notes</string>
+					<key>TeamIdentifier</key>
+					<string>0000000000</string>
+					<key>Name</key>
+					<string>Notes</string>
+				</dict>
+			</dict>
+		</dict>
+		<dict>
+			<key>WFWorkflowActionIdentifier</key>
+			<string>is.workflow.actions.gettext</string>
+			<key>WFWorkflowActionParameters</key>
+			<dict>
+				<key>UUID</key>
+				<string>01BCDBDD-C08D-5147-9FA4-EAA5AEE0249C</string>
+				<key>WFTextActionText</key>
+				<string>APPLE_NOTES_MARKDOWN_V1_DONE</string>
+			</dict>
+		</dict>
+		<dict>
+			<key>WFWorkflowActionIdentifier</key>
+			<string>is.workflow.actions.output</string>
+			<key>WFWorkflowActionParameters</key>
+			<dict>
+				<key>UUID</key>
+				<string>3E99E727-244A-5162-808E-627E927B0BA7</string>
+				<key>WFOutput</key>
+				<dict>
+					<key>WFSerializationType</key>
+					<string>WFTextTokenString</string>
+					<key>Value</key>
+					<dict>
+						<key>string</key>
+						<string></string>
+						<key>attachmentsByRange</key>
+						<dict>
+							<key>{0, 1}</key>
+							<dict>
+								<key>Type</key>
+								<string>ActionOutput</string>
+								<key>OutputUUID</key>
+								<string>01BCDBDD-C08D-5147-9FA4-EAA5AEE0249C</string>
+								<key>OutputName</key>
+								<string>op-create-markdown-ok</string>
+							</dict>
+						</dict>
+					</dict>
+				</dict>
+			</dict>
+		</dict>
+		<dict>
+			<key>WFWorkflowActionIdentifier</key>
+			<string>is.workflow.actions.conditional</string>
+			<key>WFWorkflowActionParameters</key>
+			<dict>
+				<key>UUID</key>
+				<string>64FA875D-F93B-5A6E-91E2-888D6F3192AF</string>
+				<key>GroupingIdentifier</key>
+				<string>0DD3CC74-CF2E-5A9D-AE11-C1DC205557E8</string>
+				<key>WFControlFlowMode</key>
+				<integer>2</integer>
+			</dict>
+		</dict>
+		<dict>
+			<key>WFWorkflowActionIdentifier</key>
+			<string>is.workflow.actions.gettext</string>
+			<key>WFWorkflowActionParameters</key>
+			<dict>
+				<key>UUID</key>
+				<string>E3837313-32E2-513F-9F22-48146FAB7FCC</string>
+				<key>WFTextActionText</key>
+				<string>APPLE_NOTES_MARKDOWN_V1_REFUSED</string>
+			</dict>
+		</dict>
+		<dict>
+			<key>WFWorkflowActionIdentifier</key>
+			<string>is.workflow.actions.output</string>
+			<key>WFWorkflowActionParameters</key>
+			<dict>
+				<key>UUID</key>
+				<string>461330AD-B74B-54C8-BE23-04649AA3DCE8</string>
+				<key>WFOutput</key>
+				<dict>
+					<key>WFSerializationType</key>
+					<string>WFTextTokenString</string>
+					<key>Value</key>
+					<dict>
+						<key>string</key>
+						<string></string>
+						<key>attachmentsByRange</key>
+						<dict>
+							<key>{0, 1}</key>
+							<dict>
+								<key>Type</key>
+								<string>ActionOutput</string>
+								<key>OutputUUID</key>
+								<string>E3837313-32E2-513F-9F22-48146FAB7FCC</string>
+								<key>OutputName</key>
+								<string>refused</string>
+							</dict>
+						</dict>
+					</dict>
+				</dict>
+			</dict>
+		</dict>
+	</array>
+	<key>WFWorkflowClientVersion</key>
+	<string>2600</string>
+	<key>WFWorkflowMinimumClientVersion</key>
+	<integer>900</integer>
+	<key>WFWorkflowMinimumClientVersionString</key>
+	<string>900</string>
+	<key>WFWorkflowTypes</key>
+	<array/>
+	<key>WFWorkflowHasShortcutInputVariables</key>
+	<true/>
+	<key>WFWorkflowHasOutputAction</key>
+	<true/>
+	<key>WFWorkflowInputContentItemClasses</key>
+	<array>
+		<string>WFStringContentItem</string>
+		<string>WFDictionaryContentItem</string>
+		<string>WFGenericFileContentItem</string>
+	</array>
+	<key>WFWorkflowOutputContentItemClasses</key>
+	<array>
+		<string>WFStringContentItem</string>
+	</array>
+	<key>WFWorkflowIcon</key>
+	<dict>
+		<key>WFWorkflowIconStartColor</key>
+		<integer>4251333119</integer>
+		<key>WFWorkflowIconGlyphNumber</key>
+		<integer>59507</integer>
+	</dict>
+	<key>WFWorkflowImportQuestions</key>
+	<array/>
+</dict>
+</plist>

package/shortcuts/README.md

@@ -49,3 +49,35 @@ Open the signed file and confirm **Add Shortcut** once, then run it once in the
 foreground in Shortcuts.app and choose **Always Allow** (see above). Do not install obsolete
 workflow versions with the same display name; the server resolves one exact
 installed UUID and refuses duplicates.
+
+## Create Markdown Note bridge
+
+`Apple Notes MCP - Create Markdown Note.shortcut` creates one note with Notes'
+Create Note action and "Interpret as Markdown" (macOS 26+, iCloud accounts only)
+in the iCloud default folder. It is optional: only `create-note` with
+`format: "markdown"` uses it, and neither `setup --check`'s readiness nor
+`doctor`'s native-write check depends on it. It reads the same JSON request file and runs only
+for `operation: "create-markdown"`; it has no search, edit or delete actions.
+The server finds the new note by exact ID and verifies it before reporting
+success.
+
+Regenerate and test the unsigned source with:
+
+```sh
+PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-markdown-note-shortcut.py
+PYTHONDONTWRITEBYTECODE=1 python3 scripts/build-markdown-note-shortcut.py
+shortcuts sign --mode anyone \
+  --input "shortcuts/Apple Notes MCP - Create Markdown Note.unsigned.shortcut" \
+  --output "shortcuts/Apple Notes MCP - Create Markdown Note.shortcut"
+```
+
+Open the signed file and confirm **Add Shortcut** once. Then run it once in the
+foreground so macOS can ask for Notes access, and choose **Always Allow**. A
+background run cannot show that prompt and waits until the server times out.
+Run by hand with no input, the Shortcut stops before reaching Notes, so start the
+first run with a request instead. This creates a note titled "Apple Notes MCP
+check", which you can delete:
+
+```sh
+open "shortcuts://run-shortcut?name=Apple%20Notes%20MCP%20-%20Create%20Markdown%20Note&input=text&text=%7B%22operation%22%3A%22create-markdown%22%2C%22text%22%3A%22%23%20Apple%20Notes%20MCP%20check%22%7D"
+```