apple-notes-mcp

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.

<picture> <source media="(prefers-color-scheme: dark)" srcset="assets/screenshot-dark.png"> <source media="(prefers-color-scheme: light)" srcset="assets/screenshot-light.png"> <img alt="Apple Notes MCP" src="assets/screenshot-light.png"> </picture>

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 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:

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