{
  "markdown": "# mac-notes-mcp\n\nAn MCP server that lets Claude Code read, search, and edit notes in the macOS Notes app.\n\nRuns locally over stdio. Talks to Notes via JXA (`/usr/bin/osascript -l JavaScript`). Works with every Notes account on your machine — iCloud, Google, On My Mac, IMAP — without touching the Notes SQLite database directly.\n\n## Requirements\n\n- macOS (the package is marked `\"os\": [\"darwin\"]`)\n- Node.js 18 or later\n- The Notes app installed and at least one account configured\n\n## Install\n\n### Option A — Claude Code plugin marketplace (recommended)\n\nAdd the marketplace, then install the plugin:\n\n```sh\nclaude plugin marketplace add stuk88/mac-notes-mcp\nclaude plugin install mac-notes@mac-notes-mcp\n```\n\nThat's it. Claude Code spawns the MCP server automatically; no separate registration needed. The compiled `dist/` is shipped in the repo, so you don't need to run `npm install` or `npm run build`.\n\n### Option B — Standalone MCP server\n\nIf you'd rather wire it up yourself (no plugin manager):\n\n```sh\ngit clone https://github.com/stuk88/mac-notes-mcp\ncd mac-notes-mcp\nnpm install\nnpm run build\n```\n\n## Register with Claude Code (Option B only)\n\nPoint Claude Code at the compiled entry. The cleanest way is the built-in CLI:\n\n```sh\nclaude mcp add --scope user mac-notes -- node /absolute/path/to/mac-notes-mcp/dist/index.js\n```\n\nThen verify:\n\n```sh\nclaude mcp list\n```\n\nYou should see `mac-notes ... ✓ Connected`.\n\n## Permissions\n\nThe first time the server tries to read or write Notes, macOS will prompt you to authorize Automation access. Approve it. If you missed the prompt, grant it manually:\n\n**System Settings → Privacy & Security → Automation** → expand the entry for your terminal (or for Claude Code) → enable **Notes**.\n\nIf you skip this, every tool call fails with `PERMISSION_DENIED` and a hint pointing here.\n\n## Tools\n\n| Tool | What it does |\n| --- | --- |\n| `list_accounts` | Returns every Notes account with its folders. |\n| `list_folders` | Flat list of folders across all accounts. |\n| `list_notes` | List notes, optionally restricted to one folder. Default limit 50, max 500. |\n| `search_notes` | Case-insensitive substring search across note titles and/or bodies. HTML tags are stripped before matching. |\n| `read_note` | Fetch a note by id. Returns both HTML body and a plain-text rendering. |\n| `create_note` | Create a new note in a folder. `body` defaults to plain text (each line wrapped in `<div>`); pass `bodyFormat: \"html\"` for raw HTML. |\n| `append_to_note` | Append content to an existing note. |\n| `update_note` | Replace a note's title and/or body. |\n\n### Addressing folders\n\nA \"Notes\" folder usually exists in multiple accounts. Two ways to disambiguate:\n\n- Pass `folderId` (the stable CoreData URI returned by `list_folders` / `list_accounts`).\n- Pass `account` and `folderName` together (e.g. `account: \"iCloud\"`, `folderName: \"Notes\"`).\n\nWithout either, `create_note` writes to the default account's default folder.\n\n### Examples\n\n```jsonc\n// Find every account and folder\n{ \"name\": \"list_accounts\" }\n\n// Search the iCloud Notes folder for a substring\n{\n  \"name\": \"search_notes\",\n  \"arguments\": {\n    \"query\": \"weekly review\",\n    \"account\": \"iCloud\",\n    \"folderName\": \"Notes\",\n    \"limit\": 20\n  }\n}\n\n// Create a plain-text note\n{\n  \"name\": \"create_note\",\n  \"arguments\": {\n    \"title\": \"Grocery list\",\n    \"body\": \"milk\\neggs\\nbread\",\n    \"account\": \"iCloud\",\n    \"folderName\": \"Notes\"\n  }\n}\n\n// Append to an existing note\n{\n  \"name\": \"append_to_note\",\n  \"arguments\": {\n    \"id\": \"x-coredata://.../ICNote/p274\",\n    \"body\": \"another bullet\",\n    \"separator\": \"\\n\"\n  }\n}\n```\n\n## What this server does NOT do\n\n- **Delete notes or folders.** Out of scope by design. Doing so safely requires a user confirmation step that doesn't exist in MCP yet.\n- **Manage attachments, links, or password-protected notes.**\n- **Bulk export.** This is for interactive Claude Code workflows, not migrations.\n\n## Development\n\n```sh\ngit clone <repo>\ncd notes-connector-claude-code\nnpm install\nnpm run build      # compile TS -> dist/\nnpm test           # run integration tests against the real Notes app\n```\n\nThe integration test creates a folder named `mcp-test-<uuid>` in your default account, exercises every tool, and deletes the folder at the end. If a run is interrupted, the folder may need manual cleanup (look in the Notes sidebar).\n\nDesign decisions and trade-offs live in [`design-log/0001-mac-notes-mcp.md`](design-log/0001-mac-notes-mcp.md).\n\n## Author\n\nBuilt by **[Stas Arshanski](https://github.com/stuk88)** at **[Kolivri.com](https://kolivri.com)**.\nIssues and pull requests welcome at [github.com/stuk88/mac-notes-mcp](https://github.com/stuk88/mac-notes-mcp).\n\n## License\n\nMIT &copy; Stas Arshanski / [Kolivri.com](https://kolivri.com)\n",
  "bytes": 4780,
  "sha": "78f0aed593592ea3ed4dc6367fc7ee3c2b59b6670ad886c2fa518d028d1eeef6",
  "repo_slug": "stuk88/mac-notes-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_stuk88_mac_notes_mcp_mac_notes_dc9bebea/readme"
}