An MCP server that lets AI agents (Claude Code, Codex, Grok Build, OpenCode, Gemini CLI, pi, …) read and edit Apple Notes on macOS, with native formatting. Every tool is also a command-line command, so an agent can use a skill instead of the server. Its settings window finds the agents on your Mac and sets each one up either way with one click, installing the ones you are missing.

Requires macOS 26 or later on Apple silicon; developed and tested on macOS 27.0.1. All code is written for this project, with no third-party dependencies. The permissions it needs are Full Disk Access (to read the Notes database) and Automation → Notes (to upload, move and delete).

Tool What it does

overview The folders with note counts, the smart folders and the tags; or the notes one per line (id, version, title, date, size, attachments, description) of a folder, a smart folder or Recently Deleted, narrowed by dates, tags, groups (only: pinned, shared, locked, quick-notes, math-notes, calls, checklists, unchecked, tagged, untagged, mentions) and attachment kinds, sorted by modified, created, last opened or title. undescribed: true lists notes that still need a description, with their opening text

search Full-text search of titles, text and the text Notes found in attachments (recognized in images and scans, handwriting, recording transcripts), best matches first, with the text around each match; with the same narrowing as overview

read_note A note as Markdown with its version: by id, several ids, or exact title; one section, or an outline with each section's size. The header says whether it is pinned or shared, and which notes link to it

read_attachment An attachment from a placeholder: images (scaled), scan pages, drawings, PDFs (text and file), audio (recordings with Notes' transcript and summary), a frame of a video, tables, links and files, with any text Notes recognized in it

describe_note Saves one-line descriptions that overview shows, many notes per call

create_note A new note from Markdown, in any folder, attaching files and link cards; or a copy of a note with everything in it (copy_of)

edit_note Several changes in one call: exact replacements, Markdown inserted at the start, the end or under a heading (list items join that section's list), or a whole rewrite; ticking or unticking checklist items by their text, ticking or unticking them all, moving ticked items to the bottom or deleting them; pinning

move_note Moves a note, or several, to another folder of its account, or back out of Recently Deleted

delete_note Moves a note, or several, to Recently Deleted

manage_folder Creates, renames, moves (into another folder, or to the top level) or deletes a folder (an empty one, or with recursive and expected_notes everything in it); creates, renames or deletes a smart folder of the notes with some tags; exports a folder and its folders as Markdown with the original attachments, to a new folder or a .zip

manage_tag Renames a tag in every note that has it, or takes it out of every note (with expected_notes)

Markdown

One note paragraph is one Markdown line, so a model can change a line without anything else moving.

Every change to a note (edit_note, move_note, delete_note) needs the version that read_note, overview or search gave, a hash of the note as Markdown. If the note changed since it was read (on another device, or by another agent), the change is refused instead of overwriting that change; each write answers with the new version. Before every edit the note's stored body is saved under ~/Library/Application Support/AppleNotesMCP/backups/<note id>/ (the last 20).

Attachments stay where they are: an edit that would drop a placeholder, or add one that is not in the note, is refused. Tables, tags, links to notes and divider lines are the exception: they can be added and removed, like text. New files and link cards come from and ; a file is taken only from the home folder (not ~/Library or a hidden folder), a temporary folder or an external drive, because this app can read every file.

A smart folder holds no notes of its own: overview and search take it to list or search the notes its rule picks, and no note can be moved into it.

Locked notes cannot be read or changed. Shared notes can be edited (the edits merge with the other people's), but are not deleted here, and a move into or out of a shared folder needs allow_shared (after asking the user).

delete_note and a recursive folder delete only move notes to Recently Deleted, and refuse a note already there (deleting it again would erase it for good). A recursive delete needs expected_notes, the number of notes the caller saw, and checks everything before it changes anything.

An export goes only to a path that does not exist yet, outside ~/Library.

Any tool can be turned off for all AI assistants in the settings window (see Choosing the tools).

Command line

Every tool is also a command, so the app works from a terminal and from an agent's shell, which is what the skill uses. A command is a noun and a verb. Its flags come from the tool's input fields, so they are the fields of the tools above. apple-notes-mcp help prints the whole tree:

apple-notes-mcp ├── --stdio Serve MCP on stdin and stdout (what agents start) ├── --settings Open the settings window (also what opening the app does) ├── --self-check Print a diagnosis ├── --version Print the version ├── help [COMMAND…] This tree, or a command's flags (also --help, -h) ├── setup Ask to control Notes, and show where to give Full Disk Access ├── skill Print the SKILL.md that teaches an agent this command line ├── agents │ ├── list Which agents are here and set up (the default) │ │ [--skill] [--folder DIR] │ ├── set-up (ID… | --all) Register the server with them, or install the skill │ │ [--restart] [--skill] [--folder DIR] │ └── install ID… Install them, then set them up │ [--dry-run] [--restart] [--skill] [--folder DIR] ├── notes │ ├── list List notes, newest first, one line each (id | version | title | date | size | description) (the default) │ │ --folder string --tag string… --only string… --attachment string… --modified-after string │ │ --modified-before string --created-after string --created-before string │ │ --sort modified|created|title|opened --[no-]undescribed --limit int │ ├── search QUERY Full-text search of titles, text and the text Notes found in attachments, best matches first │ │ --match all|any --folder string --tag string… --only string… --attachment string… │ │ --modified-after string --modified-before string --created-after string --created-before string │ │ --sort modified|created|title|opened --limit int │ ├── read [ID] Print notes as Markdown, each with the version that notes edit takes │ │ --id string… --title string --section string --[no-]outline │ ├── create MARKDOWN Create a note from Markdown; its first line is the title │ │ --folder string │ ├── copy ID Copy a note with everything in it, into its own folder or --folder │ │ --folder string │ ├── edit ID --version string Change a note in one go: --replace pairs, --insert Markdown, or --rewrite the whole note; --[no-]pinned │ │ --replace json --insert string --at string --rewrite string --check string… --uncheck string… │ │ --checklist check_all|uncheck_all|move_checked_down|delete_checked --[no-]pinned │ ├── delete [ID] Move a note to Recently Deleted (notes move brings it back; notes list --folder "Recently Deleted" lists them) │ │ --notes json --version string │ ├── move [ID] FOLDER Move a note to another folder, or back from Recently Deleted │ │ --[no-]allow-shared --notes json --version string │ └── describe --descriptions json Save one-line descriptions of notes, which notes list shows; many notes at once ├── tags │ ├── rename TAG NAME Rename a tag in every note that has it │ └── delete TAG --expected-notes int Take a tag out of every note that has it (ask the user first); the notes stay ├── attachments │ └── read ID Open an attachment from a placeholder: print its text, save its images, audio and files │ --[no-]text-only --output-dir string ├── folders │ ├── list The folders, with how many notes each holds (the default) │ │ --depth int │ ├── create PATH Create a folder; a path such as Projects/Ideas makes it inside another │ │ --tag string… --match any|all │ ├── rename FOLDER NAME Rename a folder │ │ --[no-]allow-shared │ ├── move FOLDER INTO Move a folder into another, or to the top level with "" │ │ --[no-]allow-shared │ ├── delete FOLDER Delete an empty folder, or with --recursive --expected-notes N everything in it (ask the user first) │ │ --[no-]recursive --expected-notes int │ └── export FOLDER TO Write a folder and its folders as Markdown with the original attachments, to a new folder or .zip └── call TOOL [JSON | -] Run any tool on a JSON object of its arguments; call alone lists the tools

Flag names: a field's flag has dashes for underscores, so modified_after is --modified-after.

True-or-false fields: --outline turns one on and --no-outline turns it off.

Lists: a field that holds a list repeats its flag in the singular: notes read --id 1A2B3C4D --id 5E6F7A8B.

Objects: a field of objects takes JSON: --replace '[{"old":"- [ ] Milk","new":"- [x] Milk"}]'.

Markdown from stdin: - as the Markdown of notes create, or as --insert or --rewrite, reads it from stdin, for notes of many lines.

Fields as JSON: --json '{…}' gives fields by their MCP names, and --json - reads them from stdin. Flags override them.

Any tool: call TOOL '{…}' runs a tool on its MCP arguments.

Help: --help after a command lists its flags and what each one takes.

A command prints exactly what the tool answers, which is text, often Markdown.

notes list without filters lists the newest notes; folders list gives the folder tree, which overview gives without arguments. attachments read prints what can be read from an attachment, and saves its images, audio and files to --output-dir, or to the temporary folder, printing where. Only the first word decides what the program does, so you can search for setup. Put -- before a word that starts with -.

apple-notes-mcp notes search "tax return" --folder Finance apple-notes-mcp notes read 1A2B3C4D apple-notes-mcp notes edit 1A2B3C4D --version 3f9a0c12b7e4 --insert "- [ ] Call the bank" --at "To do" apple-notes-mcp notes create - --folder Projects <<'EOF'

Trip plan

• Book the train EOF

Install

Releases are built for Apple silicon and need macOS 26 or later. The default way to install and set up is with Homebrew:

brew install --cask xiaofeng-han/tap/apple-notes-mcp apple-notes-mcp setup # allow it to control Notes; shows where to give Full Disk Access apple-notes-mcp agents set-up --all # register the server with the agents on this Mac

To give the agents the skill instead of the server, add --skill to the last command (see Server or skill).

Instead of the last two commands, you can open Apple Notes MCP from Applications: set up your agents in its AI Assistants tab, and give it its permissions under General. Without Homebrew, install from the package.

Naming the cask in full, as above, adds the tap xiaofeng-han/tap and trusts only this cask. Since Homebrew 6, items from taps outside Homebrew have to be trusted before Homebrew loads them. After that, brew upgrade picks up new releases.

Homebrew installs the same package described below, but for all users and through the macOS installer. So it asks for an administrator password, and it puts the app in /Applications. It also adds the command apple-notes-mcp (/opt/homebrew/bin/apple-notes-mcp), a small script that starts the app; the steps below use it. brew uninstall --cask apple-notes-mcp removes the app. Adding --zap also moves its settings, note backups and descriptions to the Trash.

If you installed the package for yourself before, remove that copy and point your agents at the new command (the AI Assistants tab offers Update for each). B