Apple Notes MCP 0.3.0

What's new

• More to read and find. read_attachment gives a recording's transcript and summaries, as Notes made them. search also finds the text Notes recognized in images, scans and handwriting, and in recording transcripts, and says where a hit is. overview lists Recently Deleted (with the days each note has left), the smart folders and the tags, and narrows notes by tags, groups (pinned, shared, locked, Quick Notes, Math Notes, call recordings, checklists, unticked items, mentions…) and attachment kinds, or sorts them by when they were last opened. read_note says whether a note is pinned and which notes link to it.
• New Markdown. #tag is a real Notes tag, [text](note:ID) a link to a note, --- a divider line, and <mark class="pink"> (also orange, mint, blue) keeps a highlight's color. ![name](/path/to/file) attaches a file and ![](https://…) adds a link card. Literal text that would read as one of these is written \#word or \---.
• More to change. edit_note pins and unpins, ticks and unticks checklist items by their text, and ticks all, unticks all, moves ticked items to the bottom or deletes them. create_note copies a note with everything in it (copy_of). move_note and delete_note take several notes at once. manage_folder moves a folder into another or to the top level, and makes, renames and deletes smart folders from tags. The new manage_tag renames a tag in every note or takes it out of every note.
• Every change names the version it was made against. Like Apple Reminders MCP, edit_note, move_note and delete_note now need the version that read_note, overview or search gave (every line of a list has it), and refuse a note changed elsewhere since. Calls without a version are refused, so prompts or scripts written for 0.2.0 need it added.

There are 11 tools now; manage_tag starts on unless you turned off another tool labeled Can delete. Permissions granted to 0.2.0 still apply after upgrading. Assistants started before the upgrade keep running the old server, so restart them once.

Requirements: macOS 26 or later on Apple silicon. Permissions: Full Disk Access (to read the Notes database) and Automation → Notes.

Install or upgrade

With Homebrew:

brew install --cask xiaofeng-han/tap/apple-notes-mcp   # or: brew upgrade --cask apple-notes-mcp

From the package:

gh release download v0.3.0 -R xiaofeng-han/apple-notes-mcp -p '*.pkg'
installer -pkg AppleNotesMCP-0.3.0.pkg -target CurrentUserHomeDirectory

Or open the package and choose to install for yourself only. The package has no Developer ID signature: if macOS refuses to open one downloaded in a browser, allow it under System Settings → Privacy & Security. Then open the app: set up your agents in the AI Assistants tab, pick their tools in Tools, and give it its permissions under General.

---

更新：读录音的文字稿和摘要；搜索也搜图片、扫描件、手写里识别出的字和录音文字稿；overview 列出「最近删除」、智能文件夹和标签，可按标签、分组（置顶、共享、加锁、快速备忘录、数学笔记、通话录音、清单、未勾选、提及等）和附件类型筛选，按最近打开排序；read_note 显示是否置顶和反向链接。Markdown 新增 #标签、[文字](note:ID) 笔记链接、--- 分割线、<mark class="pink"> 等高亮颜色、![名字](/路径) 加文件、![](https://…) 加链接卡片。edit_note 可置顶、按文字勾选清单项、全部勾选或取消、已勾选的移到底部或删掉；create_note 可复制整条笔记；move_note、delete_note 可一次处理多条；manage_folder 可移动文件夹、按标签建智能文件夹；新工具 manage_tag 全局改名或删除标签。改、移、删都必须带 version（照 Apple Reminders MCP），不带的调用会被拒绝。共 11 个工具，已授予的权限仍然有效；升级前启动的助手要重启一次。需要 macOS 26 或更新、Apple 芯片。详见 README（中文）。

Apple Notes MCP 0.2.0

What's new

• A command line for every tool. Each MCP tool is now a noun-verb command (notes search, notes edit, folders export, …), with flags taken from the tool's input fields, so the command line and the server accept the same things. apple-notes-mcp help prints the whole tree, call TOOL JSON runs any tool, and - as the Markdown of notes create, --insert or --rewrite reads it from stdin. attachments read saves images, audio and files to --output-dir and prints where.
• Set agents up with a skill instead of the server. apple-notes-mcp skill prints a SKILL.md that teaches an agent the command line. The AI Assistants tab can now set each agent up as MCP Server or Skill, for every project or for one project folder, and agents list/set-up/install take --skill and --folder DIR. The agent reads the skill only when notes come up, so no tool list sits in its context. Inside a sandbox (Codex runs commands in one) a missing permission is reported as such, and the agent is asked to run the command outside the sandbox.
• Choose which tools AI assistants see. A new Tools tab lists the 10 tools, each labeled Read-only, Writes or Can delete. Untick a tool and assistants no longer see it: calling it anyway, through the server or its command, is refused with a message saying where to turn it back on. All, None, Invert and Read-Only change them all at once. The choice is kept in ~/Library/Application Support/AppleNotesMCP/tools.json, so updates and reinstalls keep it, and running assistants are told of a change at once.

The MCP tools themselves are unchanged from 0.1.0. Permissions granted to 0.1.0 still apply after upgrading. Assistants started before the upgrade keep running the old server, so restart them once.

Requirements: macOS 26 or later on Apple silicon. Permissions: Full Disk Access (to read the Notes database) and Automation → Notes.

Install or upgrade

With Homebrew:

brew install --cask xiaofeng-han/tap/apple-notes-mcp   # or: brew upgrade --cask apple-notes-mcp

From the package:

gh release download v0.2.0 -R xiaofeng-han/apple-notes-mcp -p '*.pkg'
installer -pkg AppleNotesMCP-0.2.0.pkg -target CurrentUserHomeDirectory

Or open the package and choose to install for yourself only. The package has no Developer ID signature: if macOS refuses to open one downloaded in a browser, allow it under System Settings → Privacy & Security. Then open the app: set up your agents in the AI Assistants tab, pick their tools in Tools, and give it its permissions under General.

---

更新：每个工具都有了对应的命令行命令（notes search、notes edit、folders export 等），参数来自工具的输入字段，help 列出全部命令，call 可直接调用任意工具，Markdown 参数写 - 从标准输入读。新增「技能」配置方式：skill 输出教 agent 用命令行的 SKILL.md，「AI 助手」标签页可选「MCP 服务器」或「技能」，全局或指定项目文件夹，agents 命令加了 --skill 和 --folder；在沙盒里缺权限时会提示到沙盒外重跑。新增「工具」标签页：勾选开放给 AI 助手的工具（10 个，标明只读、写入或可删除），关掉的工具不出现在工具列表里，经服务器或命令行调用都会被拒绝；选择保存在 ~/Library/Application Support/AppleNotesMCP/tools.json，更新后保留，正在运行的助手会立即收到通知。MCP 工具本身与 0.1.0 相同，已授予的权限仍然有效；升级前启动的助手要重启一次。需要 macOS 26 或更新、Apple 芯片。详见 README（中文）。

Apple Notes MCP 0.1.0

The first release of Apple Notes MCP: an MCP server that lets AI agents read and edit Apple Notes with native formatting, synced through iCloud.

What it does

• Reads notes as Markdown through Notes' own data model, with the database opened read-only: titles, headings, lists, checklists, tables, links, highlights and attachments.
• Edits in place through Notes' private NotesShared framework. Only what changed is written, so formatting Markdown cannot show (colors, fonts, alignment) stays, and edits from other devices merge. Every change is rehearsed on a copy first and read back afterwards; a note changed since it was read is not overwritten.
• Uploads each change: Notes is asked to save and upload the note, and the server waits until iCloud has it.
• 10 tools: overview, search, read_note, read_attachment (images, scans, PDFs, audio, video, tables, files), describe_note, create_note, edit_note, move_note, delete_note, manage_folder (create, rename, delete, export to Markdown or .zip).
• Settings window: opens in front on the AI Assistants tab, which sets up Claude Code, Claude, Codex, Grok Build, OpenCode, Gemini CLI and Antigravity in one click; the General tab shows the two permissions.

All code is written for this project, with no third-party dependencies.

Requirements: macOS 26 or later on Apple silicon. Permissions: Full Disk Access (to read the Notes database) and Automation → Notes.

Install

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 your agents

From the package:

gh release download v0.1.0 -R xiaofeng-han/apple-notes-mcp -p '*.pkg'
installer -pkg AppleNotesMCP-0.1.0.pkg -target CurrentUserHomeDirectory

Or open the package and choose to install for yourself only. The package has no Developer ID signature: if macOS refuses to open one downloaded in a browser, allow it under System Settings → Privacy & Security. Then open the app: set up your agents in the AI Assistants tab, and give it its permissions under General.

---

首个版本：让 AI agent 以原生格式读写「备忘录」的 MCP 服务器，经 iCloud 同步。经「备忘录」自己的数据模型只读地读取笔记；经私有框架 NotesShared 原地修改，只写变化的部分，Markdown 表达不了的格式保持原样，每次修改先在副本上演练、写完再读回核对，读过之后被改过的笔记不会被覆盖；改完让「备忘录」上传并等 iCloud 收到。共 10 个工具；设置窗口打开即在最前、停在「AI 助手」页，一键配置各 agent。代码全部自写，无第三方依赖。需要 macOS 26 或更新、Apple 芯片，以及完全磁盘访问和自动化 → 备忘录两项权限。详见 README（中文）。