Labsco
MCP SERVER

Apple Notes MCP

by disco-trooper ↗

Search Apple Notes by meaning as well as keyword, with long notes chunked for accurate matching, plus full create, edit, move and delete.

Note-Taking & Personal Knowledge Bases
Summary
The search refresh policy is documented, which is rarer than it should be.

Search does not force a reindex on every request. With `INDEX_TTL` unset auto-refresh is off entirely; set it and refresh runs only after the TTL expires; and if a refresh fails or exceeds `SEARCH_REFRESH_TIMEOUT_MS` (default 2000) the search returns stale results rather than timing out. That last rule is why it stays usable on a large library. `READONLY_MODE` is there if you want search without letting anything write.

What it is

An MCP server for Apple Notes on macOS with a hybrid search index. It splits long notes into chunks so a match points at the right passage, combines vector and keyword search with Reciprocal Rank Fusion, and gives an assistant full CRUD over the notes as well.

What you get
  • Hybrid vector plus full-text search with `mode` set to hybrid, keyword or semantic, filterable by folder — `search-notes`
  • Notes listed with sorting by created, modified or title and an optional folder filter, folders listed, and a note fetched by title — `list-notes`, `list-folders`, `get-note`
  • Structured table data extracted from a note, returning rows and per-cell formatting — `get-tables`
  • Full write access — `create-note`, `update-note`, `delete-note`, `move-note`, plus `batch-move` and `batch-delete`
  • Knowledge-graph queries — `related-notes`, `list-tags`, `search-by-tag`, `export-graph`
  • Indexing you can run in the background on large vaults — `index-notes`, `start-index-job`, `get-index-job`, `list-index-jobs`, `cancel-index-job`, `reindex-note`, `purge-index`
Requirements

macOS with the Apple Notes app, and the Bun runtime — it reaches Notes through JXA. Install with `npm install -g @disco_trooper/apple-notes-mcp` and run `apple-notes-mcp`; a setup wizard walks through the embedding provider, API keys, Claude Code integration and the first index. Configuration lives in `~/.apple-notes-mcp/.env`: `OPENROUTER_API_KEY` switches to cloud embeddings, `EMBEDDING_MODEL` defaults to `Xenova/multilingual-e5-small`, and `READONLY_MODE` blocks all writes. Local embeddings are free and need roughly a 200MB download. Package version 1.8.2, MIT licensed.

Setup effort

One command — npm install -g @disco_trooper/apple-notes-mcp