mcp-apple-notes

An MCP (Model Context Protocol) server that exposes Notes.app on macOS as tools for LLM agents — list, read, create, update, delete, and search notes.

Part of the migo-mcp monorepo of independent MCP servers for Apple apps.

Requirements

• macOS (uses JXA/osascript to automate Notes.app — there's no other public API for Notes)
• Node.js 18+
• A single iCloud account in Notes.app (multi-account is not supported)

Install

npm install
npm run build

Tools

Tool	Description
list_notes	List notes (id, title, modification date), no body. Optional limit.
read_note	Read a note's full content (Markdown) by id.
create_note	Create a note from Markdown content. The first line becomes the title (that's how Notes.app derives it). Optional folder (defaults to "Notes").
update_note	Replace a note's entire content by id.
delete_note	Delete a note by id. Moves it to "Recently Deleted", same as the UI — recoverable for ~30 days.
search_notes	Case-insensitive substring search over title + content. Optional limit.

Notes:

• Content is exchanged as Markdown, not HTML. Notes.app stores bodies as HTML internally; this server converts both ways.
• Images embedded in a note's body are replaced with a [imagen adjunta] placeholder instead of being inlined as base64 — attachments are out of scope.
• "Recently Deleted" is excluded from list_notes/search_notes results.

Running it from Claude Desktop

Add it to your Claude Desktop MCP config with a local path (this package isn't published to npm):

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

The first call that touches Notes.app triggers a macOS Automation permission prompt. If it's denied or the process runs non-interactively, grant access manually in System Settings → Privacy & Security → Automation, then retry.

Development

npm run build   # compile TypeScript (tsc) to dist/
npm test        # run unit tests (node --test) against dist/**/*.test.js
npm start       # run the compiled server directly (stdio transport)

Only pure logic (Markdown↔HTML conversion, error formatting) has automated tests. Anything that touches Notes.app itself is verified manually, since it requires real macOS automation and mutates real data.

See CHANGELOG.md for release history and the repository root CLAUDE.md for architecture notes.