Apple Notes MCP

I made this because I wanted Apple Notes to feel useful inside modern AI tools.

I use Apple Notes for real things: business meetings, planning, random ideas, credentials I should probably organize better, notes spread across different accounts, and all the half-remembered stuff where I later ask, "What was that thing I talked about in that meeting?"

There are already a lot of Apple Notes MCP servers. Some of them probably work fine. But the ones I tried did not feel like they were built for how I actually want to use AI: query my notes naturally, retrieve the right context, organize notes, create new notes, and move notes between accounts without making the AI fight the tool.

So this is my version of an Apple Notes MCP: simple, local, practical, and designed for AI clients like Codex, Claude, Cursor, and anything else that speaks MCP.

Quick Links

• Install
• Codex setup
• Claude Desktop setup
• Claude Code setup
• Cursor setup
• macOS permissions
• Tool reference
• Reliability notes

What This Does

This MCP lets an AI client work with Apple Notes on your Mac.

You can ask things like:

• "Find my notes about that business meeting."
• "What did I write about the launch plan?"
• "Create a note for this idea."
• "Move this note from my personal iCloud account to my work account."
• "Organize these notes into the right folders."
• "Pull the full text of this note so we can use it as context."

The server can:

• list Apple Notes accounts;
• list folders;
• search notes by title and plaintext body;
• read full notes;
• create notes;
• update note title/body;
• move notes between folders;
• move notes across accounts;
• delete notes with dry-run safety;
• create folders.

Why This One

Apple Notes is good, but it was not designed as an AI knowledge base. MCP makes it possible to bridge that gap.

The goal here is not to be fancy. The goal is to be dependable:

• Use Apple Notes through the supported macOS automation path.
• Avoid directly reading or mutating the private Notes database.
• Return stable IDs that AI clients can use for follow-up actions.
• Default risky operations like move/delete to dry-run.
• Handle cross-account moves in a way that avoids Apple Notes' native cross-store move bug.
• Exclude Recently Deleted from normal search results so deleted notes do not look active.

Requirements

• macOS with Apple Notes installed.
• Node.js 20 or newer.
• Apple Notes accounts already signed in on the Mac.
• macOS Automation permission for whichever app launches the MCP server.

This server uses AppleScript automation. That is intentional. Apple does not provide a nice public Apple Notes API, and reading the private Notes database directly is fragile.

Install

Clone or open this project, then run:

cd /path/to/apple-notes-mcp
npm install
npm run build

For this local checkout, the path is:

cd /Users/taylorarndt/hq/developer/apple-notes-mcp
npm install
npm run build

Run Manually

npm start

Most people will not run it manually. Your MCP client will launch it for you.

MCP Configuration

Use the built dist/index.js file:

{
  "mcpServers": {
    "apple-notes": {
      "command": "node",
      "args": [
        "/Users/taylorarndt/hq/developer/apple-notes-mcp/dist/index.js"
      ]
    }
  }
}

Replace the path with wherever you installed the project.

Codex

Add the server to your Codex MCP config using the same command and args:

{
  "mcpServers": {
    "apple-notes": {
      "command": "node",
      "args": [
        "/Users/taylorarndt/hq/developer/apple-notes-mcp/dist/index.js"
      ]
    }
  }
}

Then restart Codex so it discovers the server.

Claude Desktop

Add this to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "apple-notes": {
      "command": "node",
      "args": [
        "/Users/taylorarndt/hq/developer/apple-notes-mcp/dist/index.js"
      ]
    }
  }
}

Restart Claude Desktop. The first time it tries to use Notes, macOS may ask for permission.

Claude Code

Use the same MCP server definition:

{
  "mcpServers": {
    "apple-notes": {
      "command": "node",
      "args": [
        "/Users/taylorarndt/hq/developer/apple-notes-mcp/dist/index.js"
      ]
    }
  }
}

If Claude Code cannot access Notes, check macOS Automation permissions for the terminal or app that launched it.

Cursor

In Cursor, add an MCP server with:

{
  "mcpServers": {
    "apple-notes": {
      "command": "node",
      "args": [
        "/Users/taylorarndt/hq/developer/apple-notes-mcp/dist/index.js"
      ]
    }
  }
}

Restart Cursor after adding it.

macOS Permissions

This part matters.

Apple Notes access is controlled by macOS Automation permissions. The app launching the server needs permission to control Notes.

If the server cannot access Notes:

1. Open System Settings.
2. Go to Privacy & Security.
3. Open Automation.
4. Find the app launching the MCP server.
5. Allow it to control Notes.

Depending on your setup, the app might be Claude Desktop, Cursor, Terminal, iTerm, Codex, or another MCP host.

You can test the underlying AppleScript access with:

osascript -e 'tell application id "com.apple.Notes" to get name of every account'

Then test the MCP bridge with:

npm run build
npm start

From an MCP client, call notes_status.

Tools

notes_status

Checks whether Apple Notes automation is available.

notes_list_accounts

Lists Apple Notes accounts available on the Mac.

notes_list_folders

Lists folders. You can filter by account name.

Arguments:

• accountName optional exact account name.

notes_search

Searches note titles and plaintext bodies.

Arguments:

• query optional search text.
• accountName optional exact account name.
• folderName optional exact folder name.
• limit default 25, max 200.
• includePlaintext default false.
• includeBodyHtml default false.
• includeRecentlyDeleted default false.

notes_get

Reads one full note.

Use noteId whenever possible. Titles are not unique.

Arguments:

• noteId preferred stable note ID.
• title exact title fallback.
• accountName optional disambiguator.
• folderName optional disambiguator.

notes_create

Creates a note in a target folder.

Arguments:

• title required.
• bodyHtml required.
• accountName and folderName, or accountId and folderId.

notes_update

Updates a note title and/or body.

Arguments:

• noteId preferred stable note ID.
• currentTitle exact title fallback.
• accountName optional disambiguator.
• folderName optional disambiguator.
• newTitle optional replacement title.
• bodyHtml optional replacement body.

notes_move

Moves a note to another folder. This can be in the same account or a different account.

Arguments:

• noteId preferred stable note ID.
• title exact title fallback.
• accountName optional source disambiguator.
• folderName optional source disambiguator.
• destinationAccountName optional.
• destinationFolderName optional.
• destinationAccountId optional.
• destinationFolderId optional.
• dryRun default true.

For cross-account moves, the returned note ID changes. Keep using the returned note.id.

notes_delete

Deletes a note. Defaults to dry-run.

Arguments:

• noteId preferred stable note ID.
• title exact title fallback.
• accountName optional disambiguator.
• folderName optional disambiguator.
• dryRun default true.

notes_create_folder

Creates a folder in an Apple Notes account.

Arguments:

• name required folder name.
• accountName optional.
• accountId optional.

Reliability Notes

Use IDs for anything important.

Titles and folder names are useful for humans, but they are not unique. A good AI workflow is:

1. Search notes.
2. Show or inspect the matches.
3. Use the returned noteId for read, update, move, or delete.

Move and delete default to dryRun: true. That is deliberate. It lets the AI resolve exactly what it is about to touch before it changes anything.

Cross-account moves do not use Apple Notes' native move operation. Native AppleScript moves across accounts can trigger a Core Data cross-store save error. This server handles cross-account moves with a copy-then-delete strategy and returns the new destination note ID.

Deleted notes go to Recently Deleted. Normal search excludes Recently Deleted by default so old deleted notes do not show up as active knowledge.

Tested Workflow

This has been tested end-to-end through the Node bridge used by MCP clients:

• list accounts;
• list folders;
• create a note;
• read the note;
• search for the note;
• update the note;
• dry-run a move;
• move the note across accounts;
• verify the moved note's destination and content;
• dry-run delete;
• delete;
• verify no active matching note remains.

Final test result:

{
  "ok": true,
  "created": "x-coredata://2D043C23-37C8-49EB-B30B-76080C224F76/ICNote/p460",
  "movedTo": "x-coredata://01C0A48D-207A-4C34-8F56-724B8CF4CACF/ICNote/p15",
  "finalActiveMatches": 0
}

Development

Build:

npm run build

Run:

npm start

The server uses stdio, which is what most MCP clients expect.