Apple Notes MCP
The Apple Notes MCP server lets AI agents fully manage Apple Notes on macOS, providing CRUD operations for notes and folders, content editing, search/indexing, and server controls.
Note Management
List notes (optionally filtered by folder or query); retrieve a note by ID
Create notes with title, body, and folder assignment
Update a note's title or body (replace or append); move notes between folders
Delete notes (moves to Recently Deleted)
Content Editing
Append text, hyperlinks, or checklist items to a note
Toggle or remove individual checklist items by index
Apply formatting (bold, italic, monospace) to the entire note body
Overwrite a note with a structured action plan template
Folder Management
List all accounts and folders; get folder contents (notes/subfolders, optionally recursive)
Ensure a folder path exists (creates if missing); rename or delete folders
Search & Indexing
Search notes by title or content via the Apple Notes interface
Build a local search index for faster queries; check index status; run fast index searches
Server Controls
Get server status (including safe/read-only mode state)
Toggle safe mode at runtime to enable or disable write operations
Configure write/delete permissions via environment variables (destructive deletes disabled by default)
Enables management of Apple Notes, allowing AI agents to create, read, search, organize, and format notes and folders directly through the macOS Notes application.
Integrates with the native macOS Notes app via AppleScript (osascript) to perform local-only note management, including folder organization, checklist manipulation, and content formatting.
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 Create a 'Trip Plan' note in the travel folder with a packing checklist."
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
Apple Notes MCP is a local MCP server for macOS that lets AI agents work with Apple Notes through a safe, explicit tool surface.
It is designed for agents such as Codex, Claude Desktop, Cursor, Continue, and other MCP clients that can launch a local stdio server.
What It Does
Lists Apple Notes accounts and folders
Reads notes as normalized plaintext with optional raw Apple Notes HTML
Creates, updates, moves, and deletes notes
Creates, renames, and deletes folders
Exposes read-only resources and reusable prompts for note review and rewrite workflows
Related MCP server: MCP Apple Notes
Requirements
macOS
Node.js 22 or newer
Apple Notes enabled locally
macOS Automation permission for the host app that launches the MCP server
Install For AI Agents
Use npx. You do not need to clone this repository to use the published package.
npx -y @rnto1/apple-notes-mcpThat command starts the MCP server over stdio.
MCP Client Configuration
Use the published npx package in your MCP client config.
Codex
Add this to ~/.codex/config.toml:
[mcp_servers.apple-notes]
command = "npx"
args = ["-y", "@rnto1/apple-notes-mcp"]Claude Desktop
Add this to your Claude Desktop MCP config:
{
"mcpServers": {
"apple-notes": {
"command": "npx",
"args": ["-y", "@rnto1/apple-notes-mcp"]
}
}
}Other MCP Clients
Use the same command/args pair:
{
"command": "npx",
"args": ["-y", "@rnto1/apple-notes-mcp"]
}Environment Variables
These can be set in the environment of the MCP host.
NOTES_MCP_ALLOW_WRITES=0|1Default:
1Set to
0for read-only mode.
NOTES_MCP_ALLOW_DELETES=0|1Default:
0Set to
1to allow destructive deletes without interactive confirmation.
NOTES_MCP_WARMUP=0|1Default:
1When enabled, the server proactively activates Notes and triggers the macOS Automation prompt on startup so the first real tool call does not have to discover permissions the hard way.
Example with writes disabled:
[mcp_servers.apple-notes]
command = "env"
args = [
"NOTES_MCP_ALLOW_WRITES=0",
"npx",
"-y",
"@rnto1/apple-notes-mcp"
]Tool Surface
Tools
server_statusaccounts_listfolders_listfolders_getfolders_ensurefolders_renamefolders_deletenotes_listnotes_searchnotes_getnotes_createnotes_updatenotes_movenotes_delete
Resources
applenotes://policyapplenotes://accountsapplenotes://foldersapplenotes://notes/{id}
Prompts
review-noterewrite-note
Content Model
Reads return structured note metadata plus normalized content:
idtitleaccountIdaccountNamefolderIdfolderPathcreatedAtmodifiedAtcontent.textcontent.formatcontent.htmlonly when explicitly requested
Writes are explicit:
notes_createaccepts
titleaccepts
contentaccepts
folderIdorfolderPath
notes_updateaccepts
titleaccepts exactly one of
replaceText,replaceHtml, orappendText
notes_moveaccepts
toFolderId
Safety Model
Writes are enabled by default for trusted local use.
Destructive deletes are disabled by default.
If the MCP client supports elicitation, the server can request delete confirmation.
If the client does not support elicitation, destructive deletes require
NOTES_MCP_ALLOW_DELETES=1.
Limitations
This server is
stdio-only.Apple Notes automation is limited by the Notes scripting interface on macOS.
Rich range formatting, attachments, collaboration controls, locking, and other UI-only Notes features are intentionally out of scope.
If the same folder path exists in multiple accounts, provide
accountId.
Troubleshooting
On first launch, the server proactively activates Notes so macOS can show the Automation prompt early. Approve it before retrying tool calls.
If tools fail, open Notes.app once and let sync finish.
If a delete is rejected, either confirm it through a client that supports MCP elicitation or restart the MCP host with
NOTES_MCP_ALLOW_DELETES=1.If your MCP client caches server metadata, restart the client after upgrading the package.
Contributing
Local Development
Clone the repository and install dependencies:
npm installRun the full checks:
npm run ciUseful commands:
npm run build
npm run test
npm run lint
npm run formatDevelopment Server
For local development you can run the TypeScript entrypoint directly:
npm run devFor a local packed-package check:
npm packRelease Process
Releases are automated through GitHub Actions and Changesets.
Changes merged to
maintrigger the release workflow.The workflow prepares a release via Changesets.
npm publishing uses provenance.
Repository maintainers must ensure the required GitHub secrets exist:
NPM_TOKENRELEASE_PR_TOKEN
License
MIT
Available Tools
24 toolsfolders.contentsFolder ContentsBRead-only
List notes and subfolders for a folder path.
Inputs: path (required), recursive, limit. Returns: notes, folder, subfolders
folders.deleteDelete FolderADestructive
Delete a folder by nested path (e.g., 'parent/child').
Inputs: path (required). Returns: ok
folders.ensureEnsure FolderAIdempotent
Ensure a folder path exists (e.g., 'mcp' or 'parent/child').
Inputs: path (required). Returns: folder
folders.renameRename FolderB
Rename a folder at nested path.
Inputs: path (required), newName (required). Returns: folder
notes.add_checklistAdd ChecklistB
Append checklist items to a note.
Inputs: id (required), items (required). Returns: note
notes.add_linkAdd LinkB
Append a hyperlink to a note.
Inputs: id (required), url (required), text. Returns: note
notes.append_textAppend TextB
Append plain text to a note body.
Inputs: id (required), text (required). Returns: note
notes.apply_action_plan_templateApply Action Plan TemplateB
Overwrite a note body with a professional action plan (headings, lists, timestamp).
Inputs: id (required), title, context. Returns: note
notes.apply_formatApply FormatB
Apply simple formatting to entire note body.
Inputs: id (required), mode (required). Returns: note
notes.createCreate NoteB
Create a new note with optional folder, title and body.
Inputs: folderId, title, body. Returns: note
notes.deleteDelete NoteADestructive
Delete a note by ID (moves to Recently Deleted).
Inputs: id (required). Returns: ok
notes.getGet NoteBRead-only
Fetch a note by ID.
Inputs: id (required). Returns: note
notes.index_buildBuild Search IndexB
Builds a local search index over all notes (runs in background).
Inputs: no named parameters. Returns: stats
notes.index_searchIndex SearchARead-onlyIdempotent
Fast search using the local index (run index_build first).
Inputs: query (required), limit. Returns: results
notes.index_statusIndex StatusARead-onlyIdempotent
Check if a local search index exists and when it was updated.
Inputs: no named parameters. Returns: exists, updatedAt
notes.listList NotesARead-only
List notes optionally filtered by folder or query.
Inputs: folderId, query, limit. Returns: notes
notes.list_foldersList FoldersARead-only
List all Apple Notes folders.
Inputs: no named parameters. Returns: folders
notes.moveMove NoteB
Move a note to another folder by folderId or path.
Inputs: id (required), toFolderId, toPath. Returns: note
notes.remove_checklistRemove Checklist ItemB
Remove a checklist item by index.
Inputs: id (required), index (required). Returns: note
notes.searchSearch NotesARead-only
Search notes by name (fast) or body (slower).
Inputs: query (required), inBody, limit. Returns: results
notes.toggle_checklistToggle Checklist ItemC
Toggle or set a checklist item by index.
Inputs: id (required), index (required), checked. Returns: note
notes.updateUpdate NoteB
Update a note's title/body. Optionally append body.
Inputs: id (required), title, body, append. Returns: note
server.set_safe_modeSet Safe ModeBIdempotent
Enable/disable safe (read-only) mode for write ops.
Inputs: safe (required). Returns: safeMode
server.statusServer StatusARead-onlyIdempotent
Get server status including safe mode flag.
Inputs: no named parameters. Returns: safeMode
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Most tools are clearly distinct by resource (folders vs. notes) and action, but some overlap exists: notes.search and notes.index_search both handle search, though one uses Apple's native search and the other a local index, which could cause confusion. Similarly, notes.append_text and notes.update both allow appending text, though update offers more flexibility.
Tool names follow a highly consistent verb_noun pattern with dot notation for grouping (e.g., folders.contents, notes.create). All tools use snake_case consistently, and verbs like 'list', 'get', 'create', 'update', 'delete' are applied predictably across resources.
With 24 tools, the count is on the high side for a notes management server, bordering on heavy. While it covers many operations, some tools like notes.index_build, notes.index_search, and notes.index_status for local indexing might be overkill for typical note-taking workflows, suggesting potential scope creep.
The tool set provides comprehensive CRUD and lifecycle coverage for Apple Notes, including folder management, note creation, reading, updating, deleting, moving, searching, and formatting. It also includes advanced features like checklists, links, templates, and server controls, leaving no obvious gaps for the domain.
Maintenance
Related MCP Connectors
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Save, search and edit your private notes by talking to your AI assistant.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables semantic search and retrieval of Apple Notes content, allowing AI assistants to access, search, and create notes using on-device embeddings.2MIT
- FlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants like Claude to search and reference your Apple Notes using semantic search and RAG capabilities, with fully local execution and no API keys required.7,035 npm-
- AlicenseAqualityDmaintenanceMCP server for Apple Notes with semantic search (on-device embeddings via all-MiniLM-L6-v2), full-text search, complete CRUD operations, folder management, and fuzzy title matching. 10 tools. Runs fully locally on macOS — no API keys required.1019 npm14MIT
- AlicenseAqualityBmaintenanceAn MCP server that enables LLM agents to list, read, create, update, delete, and search Apple Notes on macOS.613 npmAGPL 3.0