search-notesLABSCO 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
modeset 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, plusbatch-moveandbatch-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
USE CASES
01
Finding a note when you cannot remember the words
Run the search in semantic mode so it matches on meaning, with chunking pointing at the right passage inside a long note.
02
Pulling a table out of a note as data
Extract the structured rows and formatting instead of copying the table by hand.
03
Indexing a big library without blocking
Start a full index as a background job and poll its progress rather than waiting on a synchronous call.
04
Reorganising a folder of notes
Move or delete them in batches rather than one call per note.
05
Letting an assistant read but never write
Turn on read-only mode in the config so every write operation is blocked at the server.
22 tools
Listed in project docs. Your client may show a different list.
list-noteslist-foldersget-noteget-tablesindex-notesstart-index-jobget-index-joblist-index-jobscancel-index-jobreindex-notecreate-noteupdate-notedelete-notemove-notebatch-deletebatch-movepurge-indexlist-tagssearch-by-tagrelated-notesexport-graphBEFORE YOU INSTALL
What to know first
Tools you get
22 tools named in the project's documentation.
Requires
- apple-notes-mcp on PATH
- macOS with the Apple Notes app
- Bun runtime
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
npm install -g @disco_trooper/apple-notes-mcpMCP Clients
Claude Code
CLAUDE CODE · JSON
{
"mcpServers": {
"apple-notes": {
"command": "apple-notes-mcp",
"args": [],
"env": {}
}
}
}
