apple-notes-mcp weekly downloads statistics

Apple Notes MCP Server

A Model Context Protocol (MCP) server that lets Claude (Claude Code and Claude Desktop), Codex, and other MCP clients read, search, create, edit, organize, and export notes in Apple Notes on macOS. It runs locally on your Mac and talks to Notes through AppleScript, Apple Shortcuts, and read-only access to the Notes database.

Beyond creating and editing notes, it manages folders and accounts, native tags, checklists, tables, pinned notes, links, and attachments. It can also export notes as Markdown (through templates you can edit in a local web editor), HTML (with classic drawings as SVG), or JSON, read audio transcripts and drawings, link to single paragraphs with anchors that survive edits, and run a query language across your whole library.

<p align="center"> <img src="https://raw.githubusercontent.com/sweetrb/apple-notes-mcp/main/codex/assets/screenshot.png" alt="Apple Notes MCP — create, search, and organize Apple Notes from Codex, Claude, and other AI assistants" width="680"> </p>

Contents

• What is This? · Setup on your Mac · Requirements · Features
• Tool Reference: notes, folders, accounts, batch, export, attachments, and media, diagnostics, native background operations, private helper
• Usage Patterns · Installation choices and upgrades · Server settings · Full Disk Access · Public native helper · Permission broker
• Security and Privacy · Known Limitations · Troubleshooting · Recurring macOS permission prompts · Development

What is This?

This server acts as a bridge between AI assistants and Apple Notes. Once configured, you can ask Claude (or any MCP-compatible AI) to:

• "Save this conversation as a note called 'Meeting Summary'"
• "Find all my notes about the project deadline"
• "Read my shopping list note"
• "Move my draft notes to the Archive folder"
• "What notes do I have in my Work folder?"

The AI assistant communicates with this server, which then uses AppleScript to interact with the Notes app on your Mac. Some features also use packaged Apple Shortcuts (native tags, checklists, tables, pinning) or read the Notes database read-only (queries, checklist state, transcripts). Notes operations and speech recognition run locally. If you explicitly enable downloadAssets: true, the public helper may download speech models; what your MCP client does with tool results is up to that client.

<a id="quick-start"></a>

Setup on your Mac

Apple Notes MCP runs on the Mac that holds your Notes library. Your assistant starts a local MCP server over stdio, and the server uses AppleScript, signed Apple Shortcuts, and read-only database access. Choose one client setup below, then complete the macOS permissions and optional feature setup you need.

Version boundary: these instructions describe v2.15.1, including the optional permission broker. Normal client registration starts an in-process server unless a matching broker is already installed and answering. Broker installation is a separate opt-in step.

Manual client entries, setup commands, and the source checkout below select v2.15.1. Run setup from the same release as the server your client actually launches. The Claude Code plugin bundles its server; the Codex plugin manifest launches an unpinned npm package even when its marketplace is pinned. For reproducible Codex setup, use the manual registration below instead of the plugin. When upgrading, update the selected version consistently in the client and setup commands.

Run each setup target separately and use the exact options shown. Version 2.15.1 does not reject all unknown or mixed setup flags; a misspelled target can fall through to Shortcut setup and open import windows.

Requirements…