| name | apple-notes |
| description | Use Apple Notes from Codex through the local Apple Notes MCP plugin. Trigger for Notes account/folder lookup, note search/read/show, note creation/editing/appending/moving/deleting, and guarded folder management. |
Apple Notes
Use this skill when a task should access local Apple Notes.
Fast Routing
- First use, a new Mac, or permission failures:
notes_request_permissions.
- Find a note:
notes_search, then notes_read for selected handles.
- Browse structure:
notes_list_accounts and notes_list_folders.
- Create or organize notes: preview with
dryRun: true, then repeat with confirm: true only after the user clearly confirms.
- Open a note in the app:
notes_show.
First-run setup behavior
- If the user asks to set up the plugin, mentions a fresh clone/new Mac, or hits an access error, call
notes_request_permissions before any Notes list/search/read/write tool.
- Treat permission output as an onboarding checklist: summarize the next step in plain language, ask the user to approve macOS prompts or System Settings toggles when needed, then retry only after they say it is done.
- Do not use real note bodies to test permissions. The setup tool is the privacy-light probe.
Workflow
- Use
notes_search for title/body/folder/account/date filters. Keep limit and maxSnippetChars conservative unless the user asks for broad context.
- Use
notes_read only for selected note handles. Prefer format: "text"; request format: "html" or "both" only when editing rendered structure matters.
- Use folder handles from
notes_list_folders when the destination folder is ambiguous.
- Mutating tools are guarded:
notes_create, notes_update, notes_append, notes_move, notes_delete, notes_create_folder, notes_rename_folder, and notes_delete_folder.
- Folder deletion can affect all notes inside that folder; preview first.
Examples
Search and read a note:
notes_search({"query":"project plan","limit":5,"maxSnippetChars":500})
notes_read({"handles":["<handle-from-search>"],"format":"text","maxBodyChars":4000})
List folders and create a note in one:
notes_list_folders({"includeCounts":true})
notes_create({"title":"Meeting notes","body":"Decisions and next steps","folderHandle":"<folder-handle>","dryRun":true})
notes_create({"title":"Meeting notes","body":"Decisions and next steps","folderHandle":"<folder-handle>","confirm":true})
Append to an existing note:
notes_append({"handle":"<note-handle>","body":"Follow-up item","dryRun":true})
notes_append({"handle":"<note-handle>","body":"Follow-up item","confirm":true})
Move or delete notes:
notes_move({"handles":["<note-handle>"],"folderHandle":"<destination-folder-handle>","dryRun":true})
notes_delete({"handles":["<note-handle>"],"dryRun":true})
Access Mode
APPLE_NOTES_WRITE_MODE=ask is the default. Mutating tools return previews unless the call includes confirm: true.APPLE_NOTES_WRITE_MODE=direct means full local Notes write access.- Reads and writes require macOS Automation access to Notes for Codex or the launching terminal/app.
Privacy
Do not paste large private note bodies unless the user explicitly asks. Prefer concise summaries, handles, titles, folders, and dates.
