Apple Notes MCP Server (Rust)

A lightweight, single-binary MCP server that gives Claude full read/write access to your Apple Notes. Built in Rust for instant startup and zero runtime overhead.

Talks to the Notes app via JXA through Apple's osascript.

Requirements

• macOS (Apple Notes is macOS-only)
• An MCP-compatible client (Claude Code, Claude Desktop)

Installation

Option 1: Download pre-built binary

Download the latest release for your macOS version, extract, and place in ~/.local/bin/:

mkdir -p ~/.local/bin
tar -xzf apple-notes-mcp-*.tar.gz -C ~/.local/bin/
chmod +x ~/.local/bin/apple-notes-mcp

Then reference in your MCP config as ~/.local/bin/apple-notes-mcp.

For Claude Desktop with persistent TCC grants (optional):

~/.local/bin/apple-notes-mcp  # Download scripts/sign.sh separately and run:
./scripts/sign.sh ~/.local/bin/apple-notes-mcp

Requires a self-signed Code Signing certificate (see "Signing for Claude Desktop" below).

Option 2: Build from source

Requires Rust (rustup update).

cargo build --release
# binary at: target/release/apple-notes-mcp

For Claude Desktop, optionally sign after building:

./scripts/sign.sh

Configure your MCP client

Claude Code (~/.claude.json or /.mcp.json or ~/.claude/settings.json)

{
  "mcpServers": {
    "apple-notes": {
      "command": "~/.local/bin/apple-notes-mcp"
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "apple-notes": {
      "command": "~/.local/bin/apple-notes-mcp"
    }
  }
}

On first use, macOS will prompt to allow the binary to control Notes. Approve it.

If you are blocked and prompted to trash apple-notes-mcp:

1. click "done".
2. Open System Preferences -> Privacy & Security.
3. You should see apple-notes-mcp near the bottom. Click "Allow Anyway".
4. Restart Claude

Tools

Tool	Description
list_folders	List all folders across all accounts
list_notes	List notes, optional folder filter and limit (default 50)
get_note	Full content of a note by name
get_note_by_id	Full content of a note by id
create_note	Create a note (title, body HTML, optional folder)
search_notes	Keyword search in title/body (query), up to 25 matches
update_note	Replace a note's body by name
delete_note	Delete a note by name (moves to Recently Deleted)

Troubleshooting — macOS permissions

This server controls Notes by sending Apple Events (via osascript). macOS gates that behind permissions tied to whichever process it holds responsible for the event — usually the app that launches the server, but under Claude Desktop it's this binary itself (see "Which controlling app to use" below).

You may need to grant the controlling app:

• Automation → Notes — System Settings → Privacy & Security → Automation → find the controlling app → enable Notes.

After granting, restart the controlling app.

What the errors mean

Error	Meaning	Fix
Not authorized to send Apple events to Notes. (-1743)	Permission was denied/never granted, and the app can prompt	Grant Automation → Notes to the controlling app; see above
Application isn't running. (-600) / AppleEvent timed out (-1712)	The responsible process isn't a recognizable Apple Events client, so the event is dropped before any prompt, or Notes isn't open	Make sure Notes is open; under Claude Desktop, code-sign the binary (see "Signing for Claude Desktop")

If you were never prompted and keep getting -1743, there's a stored "deny". Re-trigger the prompt by resetting that app's Apple Events decisions, e.g.:

tccutil reset AppleEvents com.googlecode.iterm2   # iTerm2; use your app's bundle id

Which controlling app to use

macOS attaches the grant to whichever process it holds responsible for the Apple Event, which differs by host:

• Claude Code in a terminal (iTerm2 / Terminal): ✅ the terminal is the responsible app — grant it Automation → Notes and every tool call works.
• Claude Desktop: ✅ supported, with a one-time signing step. Desktop launches the server through a helper that disclaims responsibility, so the binary becomes self-responsible — the grant then attaches to apple-notes-mcp itself. For macOS to treat it as a promptable Apple Events client it needs an embedded Info.plist (it has one) and a code signature — see below.

Development

Build

cargo build --release
# binary at: target/release/apple-notes-mcp

Test

cargo test    # unit tests (escape_html, script builders, parsing, result helpers)
              # osascript tests require macOS

Certificate Signing for Claude Desktop

The binary embeds an Info.plist (bundle id + Apple Events usage string) so TCC will show a "control Notes" prompt naming Apple Notes MCP. You just need to sign it; using a stable self-signed certificate makes the granted permission persist across rebuilds (TCC keys the grant to the certificate, not the per-build hash).

1. One-time — create a self-signed Code Signing certificate. Keychain Access → Certificate Assistant → Create a Certificate… → name it Apple Notes MCP Signing, Identity Type Self-Signed Root, Certificate Type Code Signing.
2. Build and sign:

   cargo build --release
   ./scripts/sign.sh                       # uses cert "Apple Notes MCP Signing"
   # or: SIGN_IDENTITY="Your Cert Name" ./scripts/sign.sh

3. Approve the prompt. Restart Claude Desktop and run any Notes tool → macOS shows "Apple Notes MCP" wants to control "Notes" → click OK. If a stale denial blocks the prompt: tccutil reset AppleEvents com.dpidan.apple-notes-mcp first, then retry.