Apple Notes MCP Server

Read and write Apple Notes, with Apple Notes native formatting support.

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.

Requires: macOS 26 (Tahoe) or later, Node.js 24+

Setup

1. Add to your MCP client

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Claude Code — run in Terminal:

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	Read the Notes database for listing and searching
Accessibility	System Settings > Privacy & Security > Accessibility > 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 it on manually. After granting, restart your MCP client.

Which app gets the permission? macOS gives it to the app that starts the server. With Claude Desktop that is usually node. From a terminal it is the terminal app. Under a background service (for example a tunnel client), it is that service. If a toggle is on but access still fails, remove the entry with "−" and add it again with "+" — this happens when that app was updated or rebuilt.

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, newest first, one line each (50 by default), optionally filter by folder
search_notes	Full-text search across titles and note bodies, with an excerpt around each match
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:

Endpoint: http://localhost:3100/mcp/a3f8b2c9e1d4...

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.

License

MIT