apple-notes-mcp

Purpose

apple-notes-mcp is an MCP server for Apple Notes. It enables MCP-compatible clients such as Claude to search, read, create, update, delete, and manage notes in Apple Notes through natural language.

Main capabilities

• Semantic search: find notes by meaning rather than keywords.
• Hybrid search: combines vector and full-text keyword search, ranked using Reciprocal Rank Fusion.
• Chunked search: splits long notes into chunks to improve matching accuracy.
• Query cache: repeated searches are about 60 times faster.
• Knowledge graph: supports tags, links, and related note discovery, and can be exported to json or graphml format for visualization tools (such as D3.js, Gephi, yEd, Cytoscape).
• Full CRUD: create, read, update, delete, and move notes, with support for batch deletion and batch moving.
• Incremental indexing: only re-embeds changed notes.
• Background indexing tasks: supports asynchronous full or incremental indexing, with progress polling.
• Dual embedding methods: local HuggingFace or OpenRouter API.

Usage

Installation and configuration

Installation via npm is recommended. After installation, run the command; on first run, a setup wizard starts automatically, guiding you to choose an embedding provider (local or OpenRouter), configure the API key, set up Claude Code integration, and index notes. Configuration is stored in ~/.apple-notes-mcp/.env. After setup is complete, Claude Code must be restarted to use the MCP tools.

Environment requirements

• macOS (uses Apple Notes via JXA)
• The Apple Notes app with notes
• Automation permission must be granted when prompted

Search auto-refresh policy

search-notes does not force a refresh on every request: if INDEX_TTL is not set, auto-refresh is disabled, and searches use the current index; if INDEX_TTL is set, it refreshes only after the TTL is exceeded; if the refresh fails or exceeds SEARCH_REFRESH_TIMEOUT_MS, the search falls back to stale index results instead of timing out.

Embedding providers

• Local (default): uses HuggingFace Transformers and Xenova/multilingual-e5-small, free, runs locally, about 200MB download.
• OpenRouter: cloud API, fast, no local resources needed, requires an API key from openrouter.ai.

Search and Discovery

• Hybrid vector + full-text search.
• List notes, with sorting and filtering support; shows index statistics when no parameters are provided.
• When folder is provided, the server only fetches matching folders from Apple Notes, improving the speed of folder-scoped requests in large libraries.
• Example: get the 5 most recent notes { sort_by: "created", order: "desc", limit: 5 }; recently modified { sort_by: "modified", limit: 10 }; alphabetically { sort_by: "title", order: "asc", folder: "Projects" }.
• List all Apple Notes folders.
• Get note content by title.
• Extract structured table data from notes.
• Index notes for semantic search: use mode: "full" to create a chunked index to improve long-note search; the first full index is slower, subsequent searches are fast.
• For large libraries, background indexing is recommended, returning a task snapshot containing id, status, progress, with progress visible in the fetch, embed, and persist stages; poll until the status is completed, failed, or cancelled, and you may see a cancelling transitional state. Cancellation is cooperative: long steps need to reach a cancellation checkpoint, partial work may be retained, and a new task should only be started after the current task reaches cancelled.
• A single note can be reindexed after manual editing.

CRUD Operations

create-note creates a note in Apple Notes; after creating, updating, deleting, or moving, the server makes a best effort to automatically sync the vector and chunked indexes; if part of the sync fails, the tool response will include an index sync warning, in which case you can run reindex-note or index-notes. update-note updates an existing note; delete-note deletes a note (requires confirmation); move-note moves a note to another folder; supports batch delete and batch move.

Index Management

purge-index clears all index data, used to switch embedding models or repair a corrupted index; after clearing, run index-notes to rebuild.

Knowledge Graph

• List all tags and their occurrence counts.
• Find notes with a specific tag.
• Find notes related to a source note.
• Export the knowledge graph for visualization, supporting json (custom visualization, such as D3.js, web apps) and graphml (professional tools, such as Gephi, yEd, Cytoscape).

Claude Code Setup

Recommended automatic method: the setup wizard automatically adds apple-notes-mcp to Claude Code. After installation, run apple-notes-mcp. It can also be added manually to ~/.claude.json; the configuration differs between npm installation and source installation. After setup, you can use natural language to have Claude operate, for example "Search my notes for project ideas", "Create a note called 'Meeting Notes' in the Work folder", "What's in my note about vacation plans?", "Move the 'Old Project' note to Archive", "Index my notes" (after adding notes in Apple Notes).

Use Cases

Suitable for macOS users who want to use MCP clients such as Claude to efficiently retrieve and manage large numbers of Apple Notes notes through natural language, especially for users who need semantic search, knowledge graph discovery, batch operations, or indexing large note libraries.

Limitations

• Only supports macOS, depends on the Apple Notes app.
• Requires granting automation permissions.
• Write operations require setting READONLY_MODE=false in .env.
• Indexing large libraries may encounter memory issues, which can be mitigated by setting EMBEDDING_BATCH_SIZE=25, etc.
• Locked, syncing, or corrupted notes may be skipped, and need to be handled accordingly before indexing.
• Cancelling background tasks is cooperative and may retain partWork split.
• Local embedding requires downloading a model of about 200MB on first use.
• If the client calls search_notes with the parameter Keywords, it may point to another implementation; the MCP configuration needs to be pointed to apple-notes-mcp and the client restarted.

Version update highlights

• 1.9.0: During large-library indexing, note properties are read in batches to avoid indexing stalls with thousands of notes; notes that are locked or syncing are retried in batches and skipped with a report; long note reads time out (JXA_TIMEOUT_MS) and cancellation can actually stop the fetch.
• 1.8.1: list-notes folder filtering queries only the requested folder instead of scanning all notes; fixed correctness for duplicate folder names, aggregating matching folders across accounts; large-library performance is significantly improved.