apple-notes is an MCP server for semantic search and connection-discovery across the
user's own Apple Notes — hybrid search, Swanson-ABC bridges, entity threads, and cited
synthesis over everything they've written. Embeddings, search, BM25, clustering, and
bridges run on-device; only synthesis generation calls an LLM (local OR cloud,
the user's choice).
This skill covers (1) the one-time setup you must walk the user through, and (2) which
tool to reach for, since the server exposes many.
Notes ("search my notes for X", "what did I write about X", "did I ever note Y").
("find bridges/connections across my notes", "what links X and Y", "show related notes").
think about X from my notes", "pull together everything I've written on X").
If apple-notes tools are not available, the server isn't registered yet — do the
Setup below before anything else. If tools exist but a search returns "not indexed"
or empty, run index-notes first (see Ranking caveats).
The server reads Apple Notes' SQLite store directly, so the bun binary needs Full
Disk Access. Steps, in order:
brew install oven-sh/bun/bun```bash
git clone https://github.com/connerkward/mcp-apple-notes
cd mcp-apple-notes
git checkout
bun install --ignore-scripts
```
which bun, then open System Settings →Privacy & Security → Full Disk Access, click +, and add that exact bun binary
path (commonly /opt/homebrew/bin/bun or /usr/local/bin/bun). Without this the
server cannot read NoteStore.sqlite and every call fails with a permissions error.
(Review all lifecycle scripts before any separate activation; do not run postinstall merely to open a settings pane.)
claude mcp add apple-notes -- bun /absolute/path/to/mcp-apple-notes/index.ts --stdioclaude_desktop_config.json:```json
{ "mcpServers": { "apple-notes": {
"command": "/Users/
"args": ["/Users/
```
/plugin marketplace add connerkward/ckw-skills then /plugin install apple-notes@connerkward.index-notes). First index of ~1,800 notes takes a few seconds.
| Tool | Use when |
|---|---|
index-notes | First run, or to force a rebuild. Background job with live progress. |
search-notes | Default search. Hybrid semantic + BM25, re-ranked. Optional folder, modifiedAfter, modifiedBefore. "What did I write about X." |
find-notes | Exact substring match (like the Apple Notes search box). Use when the user wants a literal string, not meaning. Optional folder, date range. |
get-note | Fetch one full note by title (fuzzy fallback). |
list-notes | Notes by recency. Optional folder, date range, limit. |
list-folders | All folders + note counts. |
list-tags / search-by-tag | #hashtag inventory / notes carrying a given tag. |
related-notes | Notes related to a given one via shared tags, [[wikilinks]], and vector similarity. "Show me related notes." |
bridge-notes | Swanson-ABC bridges — non-obvious connections: pairs (A, C) not directly similar but both strongly tied to a shared intermediary B. "Find non-obvious connections across my notes." Optional folder, limit. No LLM. |
feed | Ranked evidence-first connection stream (bridges + abstraction pairs + entity threads) as JSON. Optional limit. |
entity-notes / list-entities | "Where else do I talk about Mercedes?" Entity chips → notes by mention weight. Needs the optional entity graph db (~/.mcp-apple-notes/layered_graph.db); if absent these report how to generate it. |
get-tables | Pull pipe/tab tables out of a note. |
create-note / update-note | Create or edit a note. |
check-changes | Did notes change since last index? (does not trigger re-index) |
index-health | Sync status, last-indexed time, note count. Run this if results seem stale. |
For "synthesize what I think about X" the synthesis lives in the web app endpoint
(GET /api/synthesize?q= at http://localhost:3741/ when run with bun index.ts),
which writes a grounded answer with inline [n] citations back to source notes.
index-notes.incremental index if notes changed — search returns immediately from the current index
and catches up when the job lands. If a just-edited note is missing, it's the catch-up
lag; re-run the search.
score = RRF(vector, BM25) × title_boost × recency_factor.recent, latest, today) auto-shift to a 1-day recencyhalf-life at 70% weight; normal queries keep relevance primary (90-day half-life, 10%).
Ollama (SYNTH_BASE_URL=http://localhost:1234/v1 SYNTH_MODEL=<model> OPENAI_API_KEY=local,
notes stay on-device) or real OpenAI (funded OPENAI_API_KEY, defaults to gpt-4o-mini).
Everything else — embeddings, search, BM25, clustering, bridges, entities — is on-device.
User request:
Use @apple-notes-search for this task: Semantic + keyword search and connection-discovery across the user's own Apple Notes via the apple-notes MCP server.
check-changes, index-health, or a rerun after background indexing catches up.Fork of RafalWilinski/mcp-apple-notes;
this fork reads SQLite + protobuf directly and adds bridges, entities, feed, and synthesis.
Authored by Conner K Ward. License MIT.
Pin and stage the complete external server/dependency tree, inspect executable and lifecycle entry points before activation, and explain the exact process receiving Full Disk Access. Granting broad filesystem permission requires the user’s informed action. Indexes persist note contents/embeddings: choose access, retention and deletion scope. Cloud-assisted synthesis sends selected notes to the configured provider and requires explicit private-data transfer scope; “on-device” indexing does not make cloud queries local.