Content
# Apple Notes MCP
[](https://github.com/taylorarndt/apple-notes-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://modelcontextprotocol.io/)
[](#requirements)
[](#macos-permissions)
[](package.json)
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](#install)
- [Codex setup](#codex)
- [Claude Desktop setup](#claude-desktop)
- [Claude Code setup](#claude-code)
- [Cursor setup](#cursor)
- [macOS permissions](#macos-permissions)
- [Tool reference](#tools)
- [Reliability notes](#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:
```bash
cd /path/to/apple-notes-mcp
npm install
npm run build
```
For this local checkout, the path is:
```bash
cd /Users/taylorarndt/hq/developer/apple-notes-mcp
npm install
npm run build
```
## Run Manually
```bash
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:
```json
{
"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:
```json
{
"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:
```json
{
"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:
```json
{
"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:
```json
{
"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:
```bash
osascript -e 'tell application id "com.apple.Notes" to get name of every account'
```
Then test the MCP bridge with:
```bash
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:
```json
{
"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:
```bash
npm run build
```
Run:
```bash
npm start
```
The server uses stdio, which is what most MCP clients expect.
