MCP Apple Notes

MCP Apple Notes is a local-first Apple Notes intelligence system. It is designed around a reusable Notes adapter, a thin MCP capability layer, deferred local storage, and CLI access.

This is not a Claude-specific project. Claude Desktop is one possible consumer alongside Claude Code, GitHub Copilot, OpenAI Codex, Cursor, future MCP-compatible agents, CLI workflows, and custom local apps.

Current Status

Phase 1 has a reusable Apple Notes adapter MVP. It includes a JXA-backed script boundary, structured errors, timeout handling, search/read/read-folder/create/append methods, dry-run support for writes, diagnostics, and unit tests.

The MCP server is now implemented over stdio with search, read, read-folder, create, append, and diagnostics tools. The read_folder tool reads every note body in a folder in a single JXA call — suitable for bulk analysis without per-note round-trips. Storage is explicitly deferred for v1 because the current release does not need cache, metadata, or sync state. The CLI is implemented for local diagnostics and manual adapter operations.

Current packages:

• @mcp-apple-notes/notes-adapter: reusable Apple Notes service boundary.
• @mcp-apple-notes/mcp-server: MCP stdio server exposing Apple Notes tools.
• @mcp-apple-notes/storage: deferred workspace placeholder for a future metadata and cache boundary.
• @mcp-apple-notes/cli: local command-line boundary for diagnostics and manual adapter operations.

Development

npm install
npm run build
npm test

The project uses TypeScript, Node.js ESM, npm workspaces, and Node's built-in node:test runner.

CLI

After building, run the local CLI through npm:

npm run cli -- --help
npm run cli -- diagnostics
npm run cli -- search --query "project memory" --limit 5
npm run cli -- read --id "<note-id>"
npm run cli -- read-folder --folder "2024"
npm run cli -- read-folder --folder "2024" --account "iCloud"
npm run cli -- create-preview --title "Draft" --body "Body"
npm run cli -- create --title "Draft" --body "Body"
npm run cli -- append-preview --id "<note-id>" --content "New section"
npm run cli -- append --id "<note-id>" --content "New section"

Add --json to any command for machine-readable output.

If you install the CLI package directly, the executable name is mcp-apple-notes-cli so it does not collide with the MCP server executable.

Exit codes:

• 0: success.
• 1: adapter or Apple Notes operation failed.
• 2: CLI usage error.
• 3: unexpected CLI failure.

MCP Setup

Build the server before wiring a local checkout into an MCP client:

npm install
npm run build --workspace @mcp-apple-notes/mcp-server

Claude Desktop config snippet:

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

Cursor config snippet:

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

After connecting the server, a minimal live smoke test is asking the client to run search_notes with:

{
	"folder": "Notes",
	"query": "2026-05-10",
	"limit": 1
}

Example agent interaction:

User: Search my Notes folder for 2026-05-10.
Assistant: Calling search_notes with {"folder":"Notes","query":"2026-05-10","limit":1}
Tool result: 1 note found titled "2026-05-10"
Assistant: I found one note titled 2026-05-10 in Notes. I can read it next if you want.

The server also exposes search_tags for hashtags in Apple Notes titles and bodies. Large Notes libraries can be slow through Apple Events, so tag search accepts folder, limit, maxNotes, and timeBudgetMs and may return truncated: true with partial results instead of waiting indefinitely.

Bulk folder reads

The read_folder tool reads the full plain-text body of every note in a folder in a single JXA call. This avoids per-note round-trips and is the correct approach for bulk analysis such as annual reviews, summaries, or prompt-based processing.

{
	"folder": "2024",
	"account": "iCloud"
}

The tool returns an array of NoteContent objects, each with id, title, folder, account, createdAt, updatedAt, and body (plain text). The account field is optional and scopes the folder lookup when multiple accounts share a folder name.

Apple Notes Permissions

Apple Notes access uses local macOS automation through /usr/bin/osascript. See macOS Permissions before running integration operations against Notes.

Architecture

Start with:

• System Overview
• Architecture
• Folder Structure
• Risks And Limitations