Lets an AI client read, search, create, edit, and organize notes, folders, and attachments in Apple Notes on macOS.
Also known as sweetrb/apple-notes-mcp
- Stars
- 193
- Tools
- 94
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is Apple Notes MCP?
Apple Notes lets an AI client read, search, create, edit, and organize notes, folders, and attachments in Apple Notes on macOS. It exposes 94 tools, such as code, not_found, ambiguous.
Summary generated from the project's README
About Apple Notes MCP server
Managing your personal knowledge base through an AI assistant is possible with this tool. It allows Claude, Codex, and other MCP clients to interact directly with Apple Notes on macOS. By running locally via stdio, the server connects to your notes using AppleScript, Apple Shortcuts, and read-only database access to perform tasks like searching, creating, editing, and organizing content.
Users can manage complex note structures including folders, native tags, checklists, tables, and pinned notes. The server also handles attachments and can export information into Markdown, HTML, or JSON formats. It supports advanced features like reading audio transcripts, decoding classic drawings, and using a query language to search your entire library. Because it operates on your local machine, it relies on macOS permissions like Full Disk Access and Automation rather than external API keys or accounts.
What you can do with it
- 1Automated note creationAsk your AI assistant to save a specific conversation or meeting summary directly into a new note.
- 2Library organizationInstruct the client to move specific draft notes into an archive folder to keep your workspace clean.
- 3Information retrievalSearch through your entire collection of notes to find specific details about project deadlines.
- 4Content extractionConvert your existing notes into different formats like Markdown or HTML for use in other applications.
Written from the project's README. Every use case is checked against a quote from it.
How to install Apple Notes MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Apple Notes MCP in Claude Code
$ claude mcp add apple-notes-mcp -- npx -y apple-notes-mcpInstall Apple Notes MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"apple-notes-mcp": {
"command": "npx",
"args": [
"-y",
"apple-notes-mcp"
]
}
}
}Install Apple Notes MCP in VS Code
.vscode/mcp.json
{
"servers": {
"apple-notes-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"apple-notes-mcp"
]
}
}
}Install Apple Notes MCP in VS Code CLI
$ code --add-mcp '{"name":"apple-notes-mcp","type":"stdio","command":"npx","args":["-y","apple-notes-mcp"]}'Install Apple Notes MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"apple-notes-mcp": {
"command": "npx",
"args": [
"-y",
"apple-notes-mcp"
]
}
}
}Install Apple Notes MCP in Codex
$ codex mcp add apple-notes-mcp -- npx -y apple-notes-mcpInstall Apple Notes MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.apple-notes-mcp] command = "npx" args = ["-y", "apple-notes-mcp"]
Install Apple Notes MCP in Gemini CLI
$ gemini mcp add -s user apple-notes-mcp npx -- -y apple-notes-mcpInstall Apple Notes MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"apple-notes-mcp": {
"command": "npx",
"args": [
"-y",
"apple-notes-mcp"
]
}
}
}Apple Notes MCP tools 94
Detected from the READMEcodenot_foundambiguouspermission_deniedfull_disk_access_missingshortcut_not_installedtimeout_indeterminateverification_failedrevision_conflictvalidation_errorunsupportednotes_unavailable
Show all 94 toolsShow fewer tools
operation_failedtitlecontenttagsfolderaccountformatquerylimitoffsetuniquesharedmissingcontainsmatchblockIndexoccurrencerefreshstatusestextinlinecardnotesectionkindsseparatelyifFolderIdifAncestorFolderIdforbiddenAncestorFolderIdspositionseparatorurlmodelabellinkedsincenamenotesidsreturnedwraptemplateexpandedforcekindrecentlysupportedattachmentIdstatuslocalepartialerrorindeterminatenonepathfilenamepasteboard_access_deniedpasteboard_emptyunsupported_contentmultiple_filesmultiple_itemstoo_largefile_unreadablepasteboard_changedpasteboard_timeoutpasteboard_unavailablewrite_failedassetPathspreviewPathpathssafelossygeometry-approximationpaint-approximationdrop-contentreasonunsupported_platformnot_implementedunknown_os_versionshortcuts_unavailablerowspinned
Configuration
APPLE_NOTES_MCP_TIMEOUT_MS
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubApple 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.
Contents
- What is This? · Setup on your Mac · Requirements · macOS compatibility · 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.
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
- macOS with Notes.app and at least one configured Notes account. Features depend on the installed macOS version and account type; inspect
get-capabilitiesbefore relying on optional features. - Node.js 20 or newer. The
npxexamples also need npm, normally included with Node.js. - A client that can launch a local stdio MCP server on this Mac. The configurations below cover Claude Code, Claude Desktop, Codex, Hermes, and Antigravity.
- Automation permission to control Notes.app for AppleScript operations. Database-backed operations also need Full Disk Access for the process macOS holds responsible for the server.
- Apple Shortcuts for native writes such as native tags, checklists, tables, pinning, and rich append. The optional native Markdown creation route needs macOS 26 or newer and an iCloud account.
- An Apple developer toolchain only if you choose to build an optional native helper or permissions window. The public helper builds with older SDKs too; only a macOS 26 or newer SDK compiles in its
SpeechAnalyzerroute (see macOS compatibility).
macOS compatibility
What works depends on the macOS release. get-capabilities reports this for the Mac it runs on (features.<name>.minimumMacOSVersion, osSupported, and a reason such as requires_macos_13), so check it there rather than relying on this table alone. The server is developed and tested on current macOS; rows for older releases come from each feature's declared minimum and Apple's API availability, not from testing on those releases.
| Feature | macOS 12 | macOS 13–15 | macOS 26 and later |
|---|---|---|---|
AppleScript core: create, read, search, update, move and delete notes and folders (applescriptCore) |
Yes | Yes | Yes |
Notes database reads with Full Disk Access: queries, structure, checklist state, exports, attachments (fullDiskAccessReads) |
Yes | Yes | Yes |
get-note-link without Full Disk Access |
Yes, AppleScript fallback | Yes, AppleScript fallback | No, needs Full Disk Access |
Listing bridge Shortcuts (doctor, setup --check, shortcutsBridges) |
Yes, by name (12's shortcuts list cannot show identifiers) |
Yes | Yes |
Native Tags and Background Operations bridges: native tags, checklists, tables, pinning, note links, append-native (nativeTagsBridge, backgroundOperationsBridge) |
No: they call Notes App Intents actions, which macOS 12 does not have | Minimum declared; untested | Yes |
Markdown note creation through the Markdown bridge (markdownNoteBridge) |
No | No | Yes, iCloud account only |
Public native helper build (setup --public-helper) |
Builds with the SDK that release's Xcode or Command Line Tools provide; not tested on macOS 12 itself | Builds | Builds |
Classic drawing decode (get-note-drawings, needs the helper and Full Disk Access) |
Yes | Yes | Yes |
On-device transcription (transcribe-note-audio, needs the helper and Full Disk Access) |
SFSpeechRecognizer: needs a Speech Recognition grant for the app that launches the server, and an on-device model for the locale |
Same as macOS 12 | SpeechAnalyzer, no grant needed, when the helper was built with a macOS 26 or newer SDK; otherwise as on macOS 12 |
Stored audio transcripts (get-audio-transcripts) |
With Full Disk Access | With Full Disk Access | With Full Disk Access |
Before macOS 13, setup does not open the Tags or Background bridge for import, and setup and setup --check report both as skipped with requires_macos_13.
The public helper compiles its SpeechAnalyzer route only when the SDK provides it. With an older SDK the same helper builds without it and transcribes through SFSpeechRecognizer on every release, even on macOS 26 and later. Node.js 20 or newer is required everywhere.
On macOS 12 the privacy panes are under System Preferences → Security & Privacy → Privacy, not System Settings. macOS never prompts for Full Disk Access on any release: nothing will ask, and you add the app or executable yourself (see which process needs it).
Python is not an Apple Notes MCP runtime dependency. The package includes its compiled JavaScript server and signed Shortcut files. Python is used by developer scripts that regenerate those workflows, not by normal installation or MCP tool calls.
You do not need an Apple ID password, API key, or NotesCTL installation to configure this server. A client's own login and tool-approval policy are separate from macOS privacy permissions.
1. Choose one client registration
Use either a plugin or a manual MCP entry for the same client. Registering both can load duplicate servers or leave you using a different package version than expected. Adding a client entry does not grant macOS permissions or import Shortcuts.
Claude Code
For the plugin, run these commands inside a Claude Code session:
/plugin marketplace add sweetrb/apple-notes-mcp#v2.15.1
/plugin install apple-notes@apple-notes-mcp
The plugin bundles the server and the Apple Notes skill. For a manual MCP registration instead, run this in your terminal:
claude mcp add apple-notes -s user -- npx -y apple-notes-mcp@latest
Check the connection with /mcp in Claude Code. claude mcp get apple-notes inspects the manually registered server. Project-scoped .mcp.json entries require workspace/server approval and can override a user-scoped entry.
Claude Desktop
Open Settings → Developer → Edit Config. Merge the following server entry into ~/Library/Application Support/Claude/claude_desktop_config.json, preserving any existing servers:
{
"mcpServers": {
"apple-notes": {
"command": "npx",
"args": ["-y", "apple-notes-mcp@latest"]
}
}
}
Fully quit and reopen Claude Desktop. This npx route does not require a preceding global npm installation. If the desktop app cannot find npx, use an absolute executable path or the fixed Node configuration below. The desktop app may have a different PATH from your interactive shell.
Codex
For the plugin and its Apple Notes skill:
codex plugin marketplace add sweetrb/apple-notes-mcp --ref v2.15.1
codex plugin add apple-notes@apple-notes-mcp
For a manual MCP registration instead:
codex mcp add apple-notes -- npx -y apple-notes-mcp@latest
The equivalent entry in ~/.codex/config.toml is:
[mcp_servers.apple-notes]
command = "npx"
args = ["-y", "apple-notes-mcp@latest"]
If codex is not on your terminal's PATH, use the desktop client's Settings → MCP servers → Add server: choose STDIO, enter npx with arguments -y and apple-notes-mcp@latest, save, and restart the server.
Restart the relevant local Codex session or client. Use /mcp in the CLI or the client's MCP settings to inspect the connection. codex mcp list lists manually configured servers. The desktop client, CLI, and IDE extension share the Codex configuration; select local execution on the Mac containing your Notes library.
The plugin's server entry runs the published npm package through unpinned npx, despite the marketplace ref above. Its server may therefore differ from v2.15.1. Use the manual entry to pin the runtime for these instructions, or run setup from the release matching the plugin's actual server. This is a different distribution path from the Claude Code plugin's bundled server.
Hermes
Register a local stdio server:
hermes mcp add apple-notes --command npx --args -y apple-notes-mcp@latest
Or merge this entry into ~/.hermes/config.yaml:
mcp_servers:
apple-notes:
command: npx
args: ["-y", "apple-notes-mcp@latest"]
Restart the Hermes session. This repository supplies an MCP configuration route for Hermes; see its CLI commands and MCP configuration reference.
Antigravity
In the IDE, open MCP Servers → Manage MCP Servers → View raw config. Merge the same mcpServers JSON entry shown for Claude Desktop into the global ~/.gemini/config/mcp_config.json, or use the workspace configuration at .agents/mcp_config.json. Refresh or restart the client so it loads the server. Google's MCP guide describes the current menu and configuration paths.
The repository's .antigravity-plugin/mcp_config.json supplies an unpinned stdio server entry; the JSON above pins the audited release. Use command and args; this package does not provide a remote serverUrl.
Gemini Spark (macOS Local MCP)
In Gemini macOS builds that offer Local MCP, open Connected Apps, click + Custom, and select Local MCP in "Set up a custom connected app". Fill in the form with:
| Field | Value |
|---|---|
| Server Name | Apple Notes |
| Description | Read, search, create, edit, organize, and export Apple Notes on this Mac. |
| Command | npx -y apple-notes-mcp@latest |
You can print these instructions from the installed server:
npx -y apple-notes-mcp setup --gemini-spark
The command only prints the guide. It exits before loading server configuration, checking Notes, or running the other setup commands, and it doesn't register the app or change permissions. Exit 0 means the guide was printed, not that Gemini connected. Run it by itself; combining it with other setup options exits 2.
Keep Sandbox settings at Default initially, then click Next and review the discovered tools and permission requests before connecting. If Gemini can't launch the server, inspect Show Logs and check whether npx is available to the app. For a stable local installation, npm install -g apple-notes-mcp provides the apple-notes-mcp command; you can also use absolute paths to your Node executable and the installed build/index.js if the app can't find them. Keep that installation available, and update the command if you move it or replace Node.
Gemini's sandbox and macOS permissions are separate. Review any additional filesystem access the launcher needs; Full Access isn't a required setup step. Automation of Notes.app enables the AppleScript tools, while database tools need the runtime's Full Disk Access. Shortcut operations need the packaged bridge setup above. After connecting, ask Gemini to run get-capabilities for tool availability, then doctor for Notes access diagnostics before attempting a write. A successful terminal check doesn't verify the permissions of Gemini's process.
This integration uses the Mac app's Local MCP command interface and the server's existing stdio transport. Availability depends on your Gemini build. Google's custom apps documentation currently describes URL-based setup in the web app; it doesn't document this local form. Cloud MCP, Gemini web/mobile, and a hosted HTTP endpoint aren't supported by this server. These instructions apply to Gemini Spark, separately from Gemini CLI and Antigravity.
Other MCP clients and remote execution
A local MCP client can use the command npx with arguments -y and apple-notes-mcp@latest. Follow that client's stdio configuration format: JSON mcpServers, TOML, and YAML are not interchangeable.
Apple Notes MCP has no built-in HTTP, SSE, WebSocket, or OAuth MCP endpoint. A cloud-only client cannot access your Mac's Notes library merely by installing the npm package in a Linux container or entering a URL. A separately managed transport bridge or client feature that delegates tool execution to your Mac needs its own configuration and security review; it is not part of this package's supported setup. GUI reveal and clipboard tools also need your logged-in desktop session.
The optional anchors serve command is a paragraph-link resolver, and templates edit is a template editor. Neither is a remote MCP server.
2. Verify the server and macOS access
In the configured client, ask it to run get-capabilities and then doctor. get-capabilities inspects feature availability without opening Notes or running the bridges. doctor also sends a read-only Apple event to Notes and may trigger the macOS Automation prompt. Run these from the actual client because a successful terminal check does not establish that a different desktop app has the same permissions.
| Access or component | What it enables | How to complete it |
|---|---|---|
| Automation of Notes.app | AppleScript reads and writes | Allow the macOS prompt for the responsible app to control Notes. Inspect Privacy & Security → Automation if access was denied. |
| Full Disk Access | Database reads, rich-content inspection and safety checks, query tools, native object reads, and database-backed exports | macOS never prompts for it. Add the responsible executable/app under Privacy & Security → Full Disk Access (macOS 12: System Preferences → Security & Privacy → Privacy), fully quit and relaunch the host, then rerun doctor. |
| Shortcut installation and consent | Native tag, checklist, table, pin, link, and append routes | Import the bridges and complete their foreground consent steps below. |
| Public helper and, where required, Speech Recognition | Classic drawing decoding and on-device audio transcription | Build the optional helper; follow the permission result from doctor or the tool. |
Which process needs Full Disk Access? macOS never shows a Full Disk Access prompt, so nothing will ask; you add the entry yourself. For a brokered session, grant the signed Apple Notes MCP Broker.app access; doctor reports whether that session uses it. Without the broker, Claude Desktop needs the exact Node executable printed by doctor; granting Claude.app alone does not reach the server in that launch path. Add that exact path: a Node found some other way (which node in a shell, another install, or a Homebrew symlink) can be a different binary. For a terminal-launched client, the terminal app is normally the responsible app; for an editor-launched server, check that editor. Most other desktop clients stay responsible for the servers they launch, so grant the client app itself (and the Node path from doctor if that alone does not work). Use the actual running client's diagnostics instead of assuming that all clients share grants.
Client sandbox access is a separate boundary. A sandboxed client must be able to launch the executable and reach its files; a brokered client also needs access to the broker's local Unix socket. Full Disk Access and Automation grants do not expand the client's sandbox. Diagnose a launch or socket-access refusal in the client before changing macOS privacy permissions.
To inspect setup from a terminal without opening permission panes or requesting Automation access:
npx -y apple-notes-mcp@latest setup --permissions --check --json
The Automation result is intentionally unknown in this mode. When you are at the Mac and want to check it, this command sends a read-only Apple event and may show the macOS consent prompt:
npx -y apple-notes-mcp@latest setup --permissions --once --probe-automation
For an interactive checklist that also opens the relevant settings panes:
npx -y apple-notes-mcp@latest setup --permissions --open --probe-automation
The command checks permissions; it does not grant them. --check and SSH sessions suppress the Automation probe even when --probe-automation is supplied. Without the probe, exit status 0 does not establish Automation access.
Full Disk Access is optional if you only need operations that can safely run through AppleScript, but many capabilities and safety checks depend on it. It can also be required by guards on existing-note writes, including rich-content and revision verification; it is not merely an enhancement for read tools. Do not interpret an unavailable database-backed feature as an empty result. In particular, sync results without database visibility do not prove that iCloud sync is idle. Use the tool reference and get-capabilities for individual requirements, and see the Full Disk Access guide.
3. Enable the native Shortcut features you need
Run explicit setup on your Mac:
npx -y apple-notes-mcp@latest setup
Approve Add Shortcut for the missing signed workflows that macOS opens:
Notes MCP TagsNotes MCP Background v6Notes MCP Markdown, offered only on macOS 26 or newer and optional for native Markdown creation
Releases before 2.16.1 installed these as Apple Notes MCP - Native Tags,
Apple Notes MCP - Background Operations v6 and Apple Notes MCP - Create Markdown Note.
Those still work. To switch to the short names, run setup after deleting the old ones
in Shortcuts.app. Delete Apple Notes MCP - Background Operations v5 in any case; the
server no longer uses it.
Then check installation:
npx -y apple-notes-mcp@latest setup --check
The first two bridges determine this check's readiness; the optional Markdown bridge is reported separately. Keep only one installed copy of each named bridge. The server refuses duplicate bridge names.
After installation or upgrade, run each installed bridge once in the foreground in Shortcuts.app and answer its access prompts. Choose Always Allow if you want that bridge to run unattended. For the Markdown bridge, use the first-run request in shortcuts/README.md; running it without input stops before it asks Notes for access. That request creates a disposable check note.
An installed bridge is not proof of consent: shortcuts list, setup --check, and doctor cannot observe the first-run consent state. A background native write can stall on an unanswered prompt. After a timeout or an indeterminate write result, read the exact note before retrying because the write may already have happened.
Apple Notes MCP questions
How do I add Apple Notes MCP to Claude Code?
Run claude mcp add apple-notes-mcp -- npx -y apple-notes-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Apple Notes MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Apple Notes MCP provide?
It exposes 94 tools, including code, not_found, ambiguous, permission_denied, full_disk_access_missing.
What can the AI assistant do with my Apple Notes?
The assistant can save conversations as notes, find specific notes, read lists, move notes to folders, and manage folders, accounts, tags, checklists, and tables.
Do I need an API key to use this server?
No, you do not need an API key, an Apple ID password, or NotesCTL to configure the server.
Does this server run in the cloud?
No, the server runs locally on your Mac and interacts with the Notes app using AppleScript and local database access.