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.

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)

Related MCP server: mcp-apple-notes

Install

npm install
npm run build

Tools

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 CLAUDE.md for architecture notes.

License

GNU AGPLv3 — see LICENSE for details.