Apple Notes MCP

Comprehensive Apple Notes MCP server for local macOS note management.

Scope

This server exposes a full practical Apple Notes toolset across accounts, folders, notes, search, attachments, and destructive actions with explicit confirmation fields.

• Account discovery
• Folder listing/create/delete
• Note listing/read/search/recent
• Note create/update/append/move/delete
• Attachment metadata listing

Prerequisites

• macOS with Apple Notes app
• Node.js 20+
• Apple Notes content synced locally (iCloud/IMAP)

Setup

1. Install dependencies and build:

cd /Users/tyler/Projects/MCP-Servers/apple-notes-mcp
npm install
npm run build

2. Add to MCP config (~/.mcp.json or your client MCP config):

{
  "mcpServers": {
    "apple-notes": {
      "command": "node",
      "args": [
        "/Users/tyler/Projects/MCP-Servers/apple-notes-mcp/dist/index.js"
      ]
    }
  }
}

3. First run permission prompt:

On first use, macOS will prompt for Automation access so osascript can control Notes. Approve access.

Run

node /Users/tyler/Projects/MCP-Servers/apple-notes-mcp/dist/index.js

Available Tools

• notes_list_accounts {}
• notes_list_folders { account_id?, account_name? }
• notes_list_notes { account_id?, account_name?, folder_id?, folder_name?, limit?, include_body? }
• notes_get_recent_notes { days?, limit?, include_body? }
• notes_get_note { note_id }
• notes_search_notes { query, account_id?, account_name?, folder_id?, folder_name?, limit?, include_body?, case_sensitive? }
• notes_create_folder { name, account_id?, account_name?, parent_folder_id?, parent_folder_name? }
• notes_delete_folder { folder_id?, folder_name?, account_id?, account_name?, confirm, reason } (destructive)
• notes_create_note { title?, body?, body_format?: "plain"|"html", account_id?, account_name?, folder_id?, folder_name? }
• notes_update_note { note_id, title?, body?, body_format?: "plain"|"html" }
• notes_append_to_note { note_id, content, content_format?: "plain"|"html", insert_blank_line? }
• notes_move_note { note_id, target_folder_id?, target_folder_name?, account_id?, account_name? }
• notes_delete_note { note_id, confirm, reason } (destructive)
• notes_list_attachments { note_id }

Destructive Safety

Destructive operations require both:

• confirm: true
• non-empty reason

This applies to:

• notes_delete_note
• notes_delete_folder

Notes

• The server uses native Apple Notes scripting via osascript -l JavaScript (JXA).
• Apple Notes does not need to be manually open. macOS auto-launches it when tools are called.
• note_id, folder_id, and account_id are stable identifiers from Apple Notes and are recommended over names.
• Attachment file export is not provided by Notes scripting directly. This server returns attachment metadata.

License

MIT

Quickstart TL;DR

npm install
npm run build
node dist/index.js

Add to MCP config:

{
  "mcpServers": {
    "apple-notes": {
      "command": "node",
      "args": ["/absolute/path/to/apple-notes-mcp/dist/index.js"]
    }
  }
}

How It Works (TL;DR)

• MCP client calls tool -> Node MCP server receives request
• Server invokes native macOS JXA (osascript -l JavaScript) against Apple Notes
• Response is normalized into JSON and returned to the MCP client
• Destructive operations require confirm: true and reason

LLM Quick Copy

Use the copy button on this code block in GitHub.

Repo: apple-notes-mcp
Goal: Local Apple Notes MCP server for macOS.
Setup:
1) npm install
2) npm run build
3) Add MCP config entry pointing to dist/index.js
4) Start your MCP client and call notes_list_accounts
How to use:
- Discover: notes_list_accounts, notes_list_folders, notes_list_notes
- Read/search: notes_get_note, notes_search_notes, notes_get_recent_notes
- Write: notes_create_note, notes_update_note, notes_append_to_note, notes_move_note
- Destructive: notes_delete_note / notes_delete_folder require confirm=true and reason
How it works:
- Node MCP wrapper -> JXA via osascript -> Apple Notes automation API