Apple Notes MCP

What disco-trooper/apple-notes-mcp MCP server does

disco-trooper/apple-notes-mcp MCP server exposes Apple Notes operations to an MCP-compatible client. It can retrieve notes by title, list folders, filter and sort note listings, extract table data, and search note content. Search supports keyword, semantic, or hybrid modes, with hybrid search combining vector and full-text results.

The server also provides write operations for creating, editing, deleting, moving, and batch-managing notes. Destructive actions require confirmation, and write operations can trigger best-effort synchronization of the search indexes. A read-only mode is available through configuration when write access should be blocked.

Its discovery features include tag counts, tag-based search, related-note lookup based on tags, links, or similarity, and knowledge-graph export. These features are useful for navigating a note library beyond exact-title or keyword matches.

How it works

The project runs on macOS and accesses Apple Notes through JXA, so Apple Notes and its notes must be available on the host machine. It maintains local indexes for search and can split long notes into chunks to improve matching. Incremental indexing reprocesses changed notes instead of rebuilding everything, while a full index can be created for broader long-note coverage.

Embedding generation defaults to the local Xenova/multilingual-e5-small Hugging Face model, which downloads approximately 200 MB and does not require a cloud API key. OpenRouter can be selected for cloud embeddings by providing OPENROUTER_API_KEY. Search results may use a current or stale index depending on the refresh configuration and timeout behavior.

For larger libraries, indexing can run as a background job. The client can start a full or incremental job, inspect its progress, list retained jobs, and request cancellation. Cancellation is cooperative, so partial work may remain.

Setup and configuration

Install the published npm package and run its apple-notes-mcp command. The first-run wizard selects the embedding provider, configures any needed API key, offers Claude Code integration, and starts indexing. The repository also documents a source setup using Bun with bun install followed by bun run start.

Configuration is stored in ~/.apple-notes-mcp/.env. Relevant settings control the embedding model and dimensions, read-only behavior, index refresh timing, search refresh timeout, background-job retention, embedding batch size, and debug logging. INDEX_TTL is optional; when it is not set, searches use the existing index without automatic refresh. The apple-notes-mcp setup command can be used to reconfigure the installation.

Tools and capabilities

The available MCP tools cover these areas:

• Search and retrieval with search-notes, list-notes, list-folders, get-note, and get-tables.
• Index creation and maintenance with index-notes, reindex-note, purge-index, and the asynchronous index-job tools.
• Note management with create-note, update-note, delete-note, move-note, batch-delete, and batch-move.
• Organization and relationship discovery with list-tags, search-by-tag, related-notes, and export-graph.

get-note accepts a title and can use a folder-qualified title for disambiguation. get-tables returns rows and formatting information for tables found in a note. purge-index requires confirmation and should be followed by indexing to restore search data.

Limitations and notes

disco-trooper/apple-notes-mcp MCP server is macOS-specific because it relies on Apple Notes through JXA. The project requires the Bun runtime even when installed from npm. Semantic search depends on an index, so newly changed notes may require automatic refresh, manual reindexing, or a full indexing job before they appear in expected results.

OpenRouter embeddings require the user's API key; the local embedding option avoids that requirement but uses local resources and requires the model download. Index refresh during search is bounded by SEARCH_REFRESH_TIMEOUT_MS; if refresh fails or exceeds that limit, the server can return results from the existing index. Index-job cancellation and post-write index synchronization are best effort rather than transactional guarantees.