Apple Notes MCP

What ailenshen/apple-notes-mcp MCP server does

ailenshen/apple-notes-mcp MCP server exposes Apple Notes operations through MCP. Agents can browse notes, optionally narrow results to a folder, search by keyword, read full notes as Markdown, create formatted notes, replace an existing note's content, and delete notes. Deletions follow the normal Notes behavior by moving items to Recently Deleted.

The server is intended for macOS systems running macOS 26 (Tahoe) or later with Node.js 24 or newer. It is a local integration with the Notes application and its on-device database, rather than a general-purpose notes API.

How it works

For listing and searching, the server performs read-only SQLite queries against the Apple Notes database. These operations are designed to be quick. When reading a note, it uses AppleScript and converts Apple's HTML representation into Markdown with the turndown library.

Creation takes a different path. The server writes Markdown to a temporary file, opens it with Notes.app, and confirms the application's import dialog. This lets headings, emphasis, lists, and inline code become Apple Notes formatting instead of remaining plain text. Notes.app may briefly appear while this happens.

An update replaces the entire note: the existing item is deleted and a new one is created in the same folder. Partial edits are not available. The server also offers an HTTP mode with a secret-bearing endpoint URL, which can be placed behind HTTPS when access from outside the local machine is required.

Setup and configuration

Install ailenshen/apple-notes-mcp MCP server through an MCP client using the package command shown below. The README provides a Claude Desktop configuration using npx -y @ailenshen/apple-notes-mcp@latest. Claude Code can also register the same command.

The process needs two macOS permissions for node. Full Disk Access allows database reads for listing and searching. Accessibility allows the process to confirm Notes.app's Markdown import dialog during note creation. After granting permissions, restart the MCP client. If a permission is missing, the server reports which permission needs attention.

For remote use, start the package with --http. The default port is 3100, and a random URL secret is generated unless a custom value is supplied with --secret. The port can be changed with --port. Internet exposure requires an HTTPS tunnel or another reverse-proxy arrangement.

Tools and capabilities

The available tools are:

• list_notes: Browse notes, with optional folder filtering.
• search_notes: Find notes using a keyword.
• get_note: Return a note's complete content as Markdown.
• create_note: Import Markdown as a newly formatted Apple Note.
• update_note: Replace a note's full content while retaining its folder.
• delete_note: Move a note to Recently Deleted.

Supported Markdown elements include headings, bold and italic text, lists, and inline code. Block quote text is retained without its indentation style. Link text remains, but URLs are lost. Tables and footnotes are unsupported.

Limitations and notes

The update operation cannot safely modify only one paragraph or another selected portion. AppleScript exposes HTML rather than the original Markdown, so the server does not provide a clean partial read-edit-write cycle.

Native formatting depends on Notes.app's import workflow and therefore requires Accessibility permission. Creating a note can bring Notes.app to the foreground briefly. The integration also depends on Apple's local Notes database and macOS application behavior; the supplied material does not describe support for Windows or Linux.