Apple Notes MCP
Provides tools for interacting with Apple Notes on macOS, enabling AI agents to list accounts and folders, search, read, create, update, move, and delete notes programmatically through the Apple Notes application.
Allows managing notes across different iCloud accounts, including listing iCloud accounts and folders, and moving notes between iCloud accounts with a copy-and-delete strategy to avoid native cross-store bugs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Apple Notes MCP Find my notes about the launch plan."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: Apple Notes MCP Server
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 buildFor this local checkout, the path is:
cd /Users/taylorarndt/hq/developer/apple-notes-mcp
npm install
npm run buildRun Manually
npm startMost 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:
Open
System Settings.Go to
Privacy & Security.Open
Automation.Find the app launching the MCP server.
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 startFrom 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:
accountNameoptional exact account name.
notes_search
Searches note titles and plaintext bodies.
Arguments:
queryoptional search text.accountNameoptional exact account name.folderNameoptional exact folder name.limitdefault25, max200.includePlaintextdefaultfalse.includeBodyHtmldefaultfalse.includeRecentlyDeleteddefaultfalse.
notes_get
Reads one full note.
Use noteId whenever possible. Titles are not unique.
Arguments:
noteIdpreferred stable note ID.titleexact title fallback.accountNameoptional disambiguator.folderNameoptional disambiguator.
notes_create
Creates a note in a target folder.
Arguments:
titlerequired.bodyHtmlrequired.accountNameandfolderName, oraccountIdandfolderId.
notes_update
Updates a note title and/or body.
Arguments:
noteIdpreferred stable note ID.currentTitleexact title fallback.accountNameoptional disambiguator.folderNameoptional disambiguator.newTitleoptional replacement title.bodyHtmloptional replacement body.
notes_move
Moves a note to another folder. This can be in the same account or a different account.
Arguments:
noteIdpreferred stable note ID.titleexact title fallback.accountNameoptional source disambiguator.folderNameoptional source disambiguator.destinationAccountNameoptional.destinationFolderNameoptional.destinationAccountIdoptional.destinationFolderIdoptional.dryRundefaulttrue.
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:
noteIdpreferred stable note ID.titleexact title fallback.accountNameoptional disambiguator.folderNameoptional disambiguator.dryRundefaulttrue.
notes_create_folder
Creates a folder in an Apple Notes account.
Arguments:
namerequired folder name.accountNameoptional.accountIdoptional.
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:
Search notes.
Show or inspect the matches.
Use the returned
noteIdfor 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 buildRun:
npm startThe server uses stdio, which is what most MCP clients expect.
Available Tools
10 toolsnotes_createA
Create a new Apple Note in a target folder. bodyHtml should be valid lightweight HTML such as div, p, ul, ol, li, h1-h3.
Inputs: title (required), bodyHtml (required), folderId, accountId, +2 more.
notes_create_folderB
Create a folder in an Apple Notes account.
Inputs: name (required), accountId, accountName.
notes_deleteBDestructive
Delete an Apple Note. Defaults to dryRun=true so clients can verify the resolved note before deletion.
Inputs: title, dryRun, noteId, folderName, +1 more.
notes_getBRead-only
Read a full Apple Note, including plaintext and HTML body.
Inputs: title, noteId, folderName, accountName.
notes_list_accountsARead-only
List Apple Notes accounts available to the current macOS user.
Inputs: no named parameters.
notes_list_foldersARead-only
List Apple Notes folders, optionally scoped to one account.
Inputs: accountName.
notes_moveADestructive
Move a note to another folder, including folders in another account. Defaults to dryRun=true so clients can verify the resolved note and destination before moving.
Inputs: title, dryRun, noteId, folderName, +5 more.
notes_searchARead-only
Search Apple Notes by title and plaintext body. Returns stable IDs for follow-up read, update, move, and delete tools.
Inputs: limit, query, folderName, accountName, +3 more.
notes_statusARead-only
Check whether Apple Notes automation is available and return account/note counts.
Inputs: no named parameters.
notes_updateA
Update a note title and/or HTML body. Prefer noteId lookup for correctness.
Inputs: noteId, bodyHtml, newTitle, folderName, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a clearly distinct purpose: status, listing accounts, listing folders, searching, reading, creating, updating, moving, deleting notes, and creating folders. No two tools overlap in functionality.
All tools follow the consistent 'notes_<action>' pattern using snake_case. Actions are clear verbs or verb-noun combinations (e.g., list_accounts, create_folder), forming a predictable naming convention.
With 10 tools, the server is well-scoped for managing Apple Notes. It covers all essential operations without being overly numerous or too sparse.
The set covers the full lifecycle of notes (CRUD plus move) and major organizational features (accounts, folders, search). Minor gaps exist, such as missing folder deletion or rename, but core workflows are well supported.
Maintenance
Related MCP Connectors
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
AI access to your aNotepad online notes: read, search, write, and organize via 22 tools.
Notes and actions in one app. Let Claude or ChatGPT read and update them.
Create, search, and update notes in an xNotepad AI notebook, with semantic search and AI Q&A.
Related MCP Servers
- AlicenseDqualityCmaintenanceEnables interaction with Apple Notes via natural language, supporting note creation, search, and retrieval with iCloud integration for seamless note management.313 npm25MIT
- FlicenseAqualityDmaintenanceEnables interaction with Apple Notes on macOS through AppleScript, allowing users to list, search, read, create, update, and delete notes across accounts and folders.71-
- AlicenseAqualityDmaintenanceEnables AI assistants to read, create, search, update, and delete Apple Notes through natural language conversation, using JXA to communicate directly with the Notes app.87,035 npm30MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude to read, write, search, and manage Apple Notes on macOS via AppleScript automation.7,035 npmMIT