Apple Notes MCP

Apple Notes MCP is a local MCP server for macOS that lets AI agents work with Apple Notes through a safe, explicit tool surface.

It is designed for agents such as Codex, Claude Desktop, Cursor, Continue, and other MCP clients that can launch a local stdio server.

What It Does

• Lists Apple Notes accounts and folders
• Reads notes as normalized plaintext with optional raw Apple Notes HTML
• Creates, updates, moves, and deletes notes
• Creates, renames, and deletes folders
• Exposes read-only resources and reusable prompts for note review and rewrite workflows

Requirements

• macOS
• Node.js 22 or newer
• Apple Notes enabled locally
• macOS Automation permission for the host app that launches the MCP server

Install For AI Agents

Use npx. You do not need to clone this repository to use the published package.

npx -y @rnto1/apple-notes-mcp

That command starts the MCP server over stdio.

MCP Client Configuration

Use the published npx package in your MCP client config.

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.apple-notes]
command = "npx"
args = ["-y", "@rnto1/apple-notes-mcp"]

Claude Desktop

Add this to your Claude Desktop MCP config:

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "@rnto1/apple-notes-mcp"]
    }
  }
}

Other MCP Clients

Use the same command/args pair:

{
  "command": "npx",
  "args": ["-y", "@rnto1/apple-notes-mcp"]
}

Environment Variables

These can be set in the environment of the MCP host.

• NOTES_MCP_ALLOW_WRITES=0|1
  • Default: 1
  • Set to 0 for read-only mode.
• NOTES_MCP_ALLOW_DELETES=0|1
  • Default: 0
  • Set to 1 to allow destructive deletes without interactive confirmation.
• NOTES_MCP_WARMUP=0|1
  • Default: 1
  • When enabled, the server proactively activates Notes and triggers the macOS Automation prompt on startup so the first real tool call does not have to discover permissions the hard way.

Example with writes disabled:

[mcp_servers.apple-notes]
command = "env"
args = [
  "NOTES_MCP_ALLOW_WRITES=0",
  "npx",
  "-y",
  "@rnto1/apple-notes-mcp"
]

Tool Surface

Tools

• server_status
• accounts_list
• folders_list
• folders_get
• folders_ensure
• folders_rename
• folders_delete
• notes_list
• notes_search
• notes_get
• notes_create
• notes_update
• notes_move
• notes_delete

Resources

• applenotes://policy
• applenotes://accounts
• applenotes://folders
• applenotes://notes/{id}

Prompts

• review-note
• rewrite-note

Content Model

Reads return structured note metadata plus normalized content:

• id
• title
• accountId
• accountName
• folderId
• folderPath
• createdAt
• modifiedAt
• content.text
• content.format
• content.html only when explicitly requested

Writes are explicit:

• notes_create
  • accepts title
  • accepts content
  • accepts folderId or folderPath
• notes_update
  • accepts title
  • accepts exactly one of replaceText, replaceHtml, or appendText
• notes_move
  • accepts toFolderId

Safety Model

• Writes are enabled by default for trusted local use.
• Destructive deletes are disabled by default.
• If the MCP client supports elicitation, the server can request delete confirmation.
• If the client does not support elicitation, destructive deletes require NOTES_MCP_ALLOW_DELETES=1.

Limitations

• This server is stdio-only.
• Apple Notes automation is limited by the Notes scripting interface on macOS.
• Rich range formatting, attachments, collaboration controls, locking, and other UI-only Notes features are intentionally out of scope.
• If the same folder path exists in multiple accounts, provide accountId.

Troubleshooting

• On first launch, the server proactively activates Notes so macOS can show the Automation prompt early. Approve it before retrying tool calls.
• If tools fail, open Notes.app once and let sync finish.
• If a delete is rejected, either confirm it through a client that supports MCP elicitation or restart the MCP host with NOTES_MCP_ALLOW_DELETES=1.
• If your MCP client caches server metadata, restart the client after upgrading the package.

Contributing

Local Development

Clone the repository and install dependencies:

npm install

Run the full checks:

npm run ci

Useful commands:

npm run build
npm run test
npm run lint
npm run format

Development Server

For local development you can run the TypeScript entrypoint directly:

npm run dev

For a local packed-package check:

npm pack

Release Process

Releases are automated through GitHub Actions and Changesets.

• Changes merged to main trigger the release workflow.
• The workflow prepares a release via Changesets.
• npm publishing uses provenance.

Repository maintainers must ensure the required GitHub secrets exist:

• NPM_TOKEN
• RELEASE_PR_TOKEN

License

MIT