Most Apple Notes MCP servers can only write plain text. This one creates natively formatted notes — Titles, Headings, Bold, Lists all render as real Apple Notes styles, not plain text. This is achieved by leveraging Notes.app's built-in Markdown import capability.
claude mcp add apple-notes -- npx -y @ailenshen/apple-notes-mcp@latest
2. Grant permissions
To support native formatting, the server uses Notes.app's built-in Markdown import — it opens .md files with Notes.app and automatically confirms the Import dialog. This requires two macOS permissions for node:
Permission
Where to enable
Why
Full Disk Access
System Settings > Privacy & Security > Full Disk Access > enable node
Auto-confirm the Import dialog when creating notes
On first use, macOS will prompt you to approve — just click Allow. If you missed the prompt, go to the settings above and turn on node manually. After granting, restart your MCP client.
If a permission is missing, the server will tell you exactly which one and how to fix it.
3. Start using it
Just talk to your AI naturally:
"List all my notes in the Projects folder"
"Search my notes for 'meeting agenda'"
"Read my Shopping List note"
"Create a note in Work with today's action items"
"Update my Shopping List with these new items"
"Delete the note called 'Old Draft'"
What Can It Do?
Tool
Description
list_notes
Browse notes, optionally filter by folder
search_notes
Find notes by keyword
get_note
Read full content as Markdown
create_note
Write Markdown → natively formatted note
update_note
Replace content, preserving folder
delete_note
Move to Recently Deleted
Markdown support in Notes
Element
Works?
Headings, bold, italic, lists, inline code
Yes
Block quotes
Content kept, no indent style
Links
Text kept, URL lost
Tables, footnotes
No
Remote Access (HTTP mode)
Want to access your Apple Notes from your phone or another computer?
npx @ailenshen/apple-notes-mcp@latest --http
This prints an endpoint URL with a built-in secret:
Point your remote MCP client to this URL. To access over the internet, put it behind HTTPS using a tunnel (ngrok, Cloudflare Tunnel, etc.).
Flag
Default
Description
--port <number>
3100
Port number
--secret <string>
random
Custom URL secret
To keep it running across reboots, see the wiki for a LaunchAgent example.
How It Works
Action
Method
Speed
List / Search
SQLite (read-only)
< 100ms
Read
AppleScript → Markdown
~1s
Create
Native Markdown import
~0.5s
Update
Delete + Create
~1.5s
Delete
AppleScript
~1s
Reading queries the Notes database directly via SQLite — fast and safe. Content is converted from Apple's HTML to Markdown via turndown.
Creating uses macOS's native Markdown import (open -a Notes), so formatting is preserved natively. Notes.app briefly appears (~0.5s) during creation.
Updating deletes the old note and creates a new one, automatically preserving the original folder.
Deleting moves notes to Recently Deleted, same as doing it by hand.
Known Limitations
Partial note editing (e.g. "fix just this paragraph") is not supported. update_note always replaces the full content. This is a fundamental limitation of how Notes exposes content — its AppleScript interface returns HTML, not the original Markdown, so a clean read→edit→write round-trip isn't possible today.
Notes briefly appears during note creation. The Markdown import flow requires auto-confirming a dialog in Notes.app, which may momentarily bring it to the foreground.
These limitations would be lifted if Apple adds Markdown import/export to AppleScript, or opens an official Notes API — both are tracked for future macOS releases.
Vision
Apple Notes is the most natural place to keep personal knowledge on Apple devices — it syncs everywhere, it's fast, and it's private. But it's a walled garden with no API.
This project makes Apple Notes a first-class data source for AI. The long-term goal: wherever you're talking to AI — on your Mac, on your phone, on the web — your Apple Notes are always accessible, readable, and writable.
