Skip to main content
Glama

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

Related MCP server: MCP Apple Notes

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

Available Tools

24 tools
folders.contentsFolder ContentsB
Read-only

List notes and subfolders for a folder path.

Inputs: path (required), recursive, limit. Returns: notes, folder, subfolders

folders.deleteDelete FolderA
Destructive

Delete a folder by nested path (e.g., 'parent/child').

Inputs: path (required). Returns: ok

folders.ensureEnsure FolderA
Idempotent

Ensure a folder path exists (e.g., 'mcp' or 'parent/child').

Inputs: path (required). Returns: folder

folders.renameRename FolderB

Rename a folder at nested path.

Inputs: path (required), newName (required). Returns: folder

notes.add_checklistAdd ChecklistB

Append checklist items to a note.

Inputs: id (required), items (required). Returns: note

notes.append_textAppend TextB

Append plain text to a note body.

Inputs: id (required), text (required). Returns: note

notes.apply_action_plan_templateApply Action Plan TemplateB

Overwrite a note body with a professional action plan (headings, lists, timestamp).

Inputs: id (required), title, context. Returns: note

notes.apply_formatApply FormatB

Apply simple formatting to entire note body.

Inputs: id (required), mode (required). Returns: note

notes.createCreate NoteB

Create a new note with optional folder, title and body.

Inputs: folderId, title, body. Returns: note

notes.deleteDelete NoteA
Destructive

Delete a note by ID (moves to Recently Deleted).

Inputs: id (required). Returns: ok

notes.getGet NoteB
Read-only

Fetch a note by ID.

Inputs: id (required). Returns: note

notes.index_buildBuild Search IndexB

Builds a local search index over all notes (runs in background).

Inputs: no named parameters. Returns: stats

notes.index_statusIndex StatusA
Read-onlyIdempotent

Check if a local search index exists and when it was updated.

Inputs: no named parameters. Returns: exists, updatedAt

notes.listList NotesA
Read-only

List notes optionally filtered by folder or query.

Inputs: folderId, query, limit. Returns: notes

notes.list_foldersList FoldersA
Read-only

List all Apple Notes folders.

Inputs: no named parameters. Returns: folders

notes.moveMove NoteB

Move a note to another folder by folderId or path.

Inputs: id (required), toFolderId, toPath. Returns: note

notes.remove_checklistRemove Checklist ItemB

Remove a checklist item by index.

Inputs: id (required), index (required). Returns: note

notes.searchSearch NotesA
Read-only

Search notes by name (fast) or body (slower).

Inputs: query (required), inBody, limit. Returns: results

notes.toggle_checklistToggle Checklist ItemC

Toggle or set a checklist item by index.

Inputs: id (required), index (required), checked. Returns: note

notes.updateUpdate NoteB

Update a note's title/body. Optionally append body.

Inputs: id (required), title, body, append. Returns: note

server.set_safe_modeSet Safe ModeB
Idempotent

Enable/disable safe (read-only) mode for write ops.

Inputs: safe (required). Returns: safeMode

server.statusServer StatusA
Read-onlyIdempotent

Get server status including safe mode flag.

Inputs: no named parameters. Returns: safeMode

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 24 tools

    Disambiguation4/5

    Most tools are clearly distinct by resource (folders vs. notes) and action, but some overlap exists: notes.search and notes.index_search both handle search, though one uses Apple's native search and the other a local index, which could cause confusion. Similarly, notes.append_text and notes.update both allow appending text, though update offers more flexibility.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun pattern with dot notation for grouping (e.g., folders.contents, notes.create). All tools use snake_case consistently, and verbs like 'list', 'get', 'create', 'update', 'delete' are applied predictably across resources.

    Tool Count3/5

    With 24 tools, the count is on the high side for a notes management server, bordering on heavy. While it covers many operations, some tools like notes.index_build, notes.index_search, and notes.index_status for local indexing might be overkill for typical note-taking workflows, suggesting potential scope creep.

    Completeness5/5

    The tool set provides comprehensive CRUD and lifecycle coverage for Apple Notes, including folder management, note creation, reading, updating, deleting, moving, searching, and formatting. It also includes advanced features like checklists, links, templates, and server controls, leaving no obvious gaps for the domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that enables semantic search and retrieval of Apple Notes content, allowing AI assistants to access, search, and create notes using on-device embeddings.
      2
      MIT
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants like Claude to search and reference your Apple Notes using semantic search and RAG capabilities, with fully local execution and no API keys required.
      7,035 npm
      -
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for Apple Notes with semantic search (on-device embeddings via all-MiniLM-L6-v2), full-text search, complete CRUD operations, folder management, and fuzzy title matching. 10 tools. Runs fully locally on macOS — no API keys required.
      10
      19 npm
      14
      MIT