Apple Notes search & connection-discovery
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.
When to Use This Skill
- Use when the user wants to find, recall, or look up something from their own Apple
Notes ("search my notes for X", "what did I write about X", "did I ever note Y").
- Use when the user wants to surface non-obvious connections across their notes
("find bridges/connections across my notes", "what links X and Y", "show related notes").
- Use when the user wants to synthesize a position from their notes ("summarize what I
think about X from my notes", "pull together everything I've written on X").
- Also use for "index my Apple Notes", tag/folder queries, and "what's connected to X".
- Do not use for creating reminders, or for non-Apple-Notes note systems.
First: is the MCP connected?
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).
Setup (walk the user through this — it's the skill's real value)
The server reads Apple Notes' SQLite store directly, so the bun binary needs Full
Disk Access. Steps, in order:
- Install bun (if absent):
brew install oven-sh/bun/bun
- Clone + install deps:
git clone https://github.com/connerkward/mcp-apple-notes
cd mcp-apple-notes
git checkout <reviewed-tag-or-commit>
bun install
- Grant Full Disk Access to bun. Run
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.
(bun install's postinstall tries to open this pane automatically.)
- Register the MCP server (pick the user's client):
- Restart the client, then tell the user to ask "Index my Apple Notes" (or call
index-notes). First index of ~1,800 notes takes a few seconds.
Tool map — which tool for which job
| 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.
Ranking caveats (state these when results look off)
- Index before the first search. No index → empty/garbage results; run
index-notes.
- Auto re-index: each search does ~1ms change detection and kicks ONE background
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:
score = RRF(vector, BM25) × title_boost × recency_factor.
- Temporal queries (
recent, latest, today) auto-shift to a 1-day recency
half-life at 70% weight; normal queries keep relevance primary (90-day half-life, 10%).
- Synthesis is the only cloud-capable part. It needs an LLM: local via LM Studio /
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.
Example
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.
Limitations
- macOS and Apple Notes only; it does not search Obsidian, Notion, Google Docs, or other note stores.
- The MCP server needs local filesystem permissions to read Apple Notes data, so setup cannot be completed purely inside a remote shell.
- Search quality depends on a fresh local index. Recently edited notes may require
check-changes, index-health, or a rerun after background indexing catches up.
- Entity tools require the optional layered graph database; without it, use hybrid search, exact search, related notes, or bridges instead.
Credits
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.
1---2name: apple-notes-search3description: "Semantic + keyword search and connection-discovery across the user's own Apple Notes via the apple-notes MCP server. Use when the user wants to find, recall, or synthesize something from their notes, or surface non-obvious bridges/related notes. macOS, on-device."4risk: critical5source: community6source_repo: connerkward/mcp-apple-notes7source_type: community8date_added: "2026-06-16"9author: connerkward10tags: [apple-notes, search, mcp, macos, semantic-search, knowledge]11tools: [claude-code]12license: "MIT"13license_source: "https://github.com/connerkward/mcp-apple-notes/blob/main/LICENSE"14plugin:15 targets:16 codex: blocked17 claude: blocked18 setup:19 type: manual20 summary: "Requires third-party MCP setup and macOS Full Disk Access; keep out of plugin-safe bundles."21 docs: SKILL.md22metadata:23 source: https://skillmd.com/skills/connerkward/apple-notes-search24---2526# Apple Notes search & connection-discovery2728`apple-notes` is an MCP server for semantic search and connection-discovery across the29user's own Apple Notes — hybrid search, Swanson-ABC bridges, entity threads, and cited30synthesis over everything they've written. Embeddings, search, BM25, clustering, and31bridges run **on-device**; only **synthesis generation** calls an LLM (local OR cloud,32the user's choice).3334This skill covers (1) the one-time setup you must walk the user through, and (2) which35tool to reach for, since the server exposes many.3637## When to Use This Skill3839- Use when the user wants to **find, recall, or look up** something from their own Apple40 Notes ("search my notes for X", "what did I write about X", "did I ever note Y").41- Use when the user wants to surface **non-obvious connections** across their notes42 ("find bridges/connections across my notes", "what links X and Y", "show related notes").43- Use when the user wants to **synthesize a position** from their notes ("summarize what I44 think about X from my notes", "pull together everything I've written on X").45- Also use for "index my Apple Notes", tag/folder queries, and "what's connected to X".46- Do **not** use for creating reminders, or for non-Apple-Notes note systems.4748## First: is the MCP connected?4950If `apple-notes` tools are not available, the server isn't registered yet — do the51**Setup** below before anything else. If tools exist but a search returns "not indexed"52or empty, run `index-notes` first (see Ranking caveats).5354## Setup (walk the user through this — it's the skill's real value)5556The server reads Apple Notes' SQLite store directly, so the **bun** binary needs Full57Disk Access. Steps, in order:58591. **Install bun** (if absent): `brew install oven-sh/bun/bun`602. **Clone + install deps:**61 ```bash62 git clone https://github.com/connerkward/mcp-apple-notes63 cd mcp-apple-notes64 git checkout <reviewed-tag-or-commit>65 bun install66 ```673. **Grant Full Disk Access to bun.** Run `which bun`, then open System Settings →68 Privacy & Security → Full Disk Access, click `+`, and add that exact `bun` binary69 path (commonly `/opt/homebrew/bin/bun` or `/usr/local/bin/bun`). Without this the70 server cannot read NoteStore.sqlite and every call fails with a permissions error.71 (`bun install`'s postinstall tries to open this pane automatically.)724. **Register the MCP server** (pick the user's client):73 - Claude Code: `claude mcp add apple-notes -- bun /absolute/path/to/mcp-apple-notes/index.ts --stdio`74 - Claude Desktop: add to `claude_desktop_config.json`:75 ```json76 { "mcpServers": { "apple-notes": {77 "command": "/Users/<you>/.bun/bin/bun",78 "args": ["/Users/<you>/mcp-apple-notes/index.ts", "--stdio"] } } }79 ```80 - As a Claude Code plugin (bundles this skill too): `/plugin marketplace add connerkward/ckw-skills` then `/plugin install apple-notes@connerkward`.815. **Restart the client**, then tell the user to ask **"Index my Apple Notes"** (or call82 `index-notes`). First index of ~1,800 notes takes a few seconds.8384## Tool map — which tool for which job8586| Tool | Use when |87|------|----------|88| `index-notes` | First run, or to force a rebuild. Background job with live progress. |89| `search-notes` | **Default search.** Hybrid semantic + BM25, re-ranked. Optional `folder`, `modifiedAfter`, `modifiedBefore`. "What did I write about X." |90| `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. |91| `get-note` | Fetch one full note by title (fuzzy fallback). |92| `list-notes` | Notes by recency. Optional `folder`, date range, `limit`. |93| `list-folders` | All folders + note counts. |94| `list-tags` / `search-by-tag` | `#hashtag` inventory / notes carrying a given tag. |95| `related-notes` | Notes related to a given one via shared tags, `[[wikilinks]]`, and vector similarity. "Show me related notes." |96| `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. |97| `feed` | Ranked evidence-first connection stream (bridges + abstraction pairs + entity threads) as JSON. Optional `limit`. |98| `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. |99| `get-tables` | Pull pipe/tab tables out of a note. |100| `create-note` / `update-note` | Create or edit a note. |101| `check-changes` | Did notes change since last index? (does not trigger re-index) |102| `index-health` | Sync status, last-indexed time, note count. Run this if results seem stale. |103104For "synthesize what I think about X" the synthesis lives in the **web app** endpoint105(`GET /api/synthesize?q=` at `http://localhost:3741/` when run with `bun index.ts`),106which writes a grounded answer with inline `[n]` citations back to source notes.107108## Ranking caveats (state these when results look off)109110- **Index before the first search.** No index → empty/garbage results; run `index-notes`.111- **Auto re-index:** each search does ~1ms change detection and kicks ONE background112 incremental index if notes changed — search returns immediately from the current index113 and catches up when the job lands. If a just-edited note is missing, it's the catch-up114 lag; re-run the search.115- **Score:** `score = RRF(vector, BM25) × title_boost × recency_factor`.116- **Temporal queries** (`recent`, `latest`, `today`) auto-shift to a 1-day recency117 half-life at 70% weight; normal queries keep relevance primary (90-day half-life, 10%).118- **Synthesis is the only cloud-capable part.** It needs an LLM: local via LM Studio /119 Ollama (`SYNTH_BASE_URL=http://localhost:1234/v1 SYNTH_MODEL=<model> OPENAI_API_KEY=local`,120 notes stay on-device) or real OpenAI (funded `OPENAI_API_KEY`, defaults to `gpt-4o-mini`).121 Everything else — embeddings, search, BM25, clustering, bridges, entities — is on-device.122123## Example124125**User request:**126127> 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.128129## Limitations130131- macOS and Apple Notes only; it does not search Obsidian, Notion, Google Docs, or other note stores.132- The MCP server needs local filesystem permissions to read Apple Notes data, so setup cannot be completed purely inside a remote shell.133- Search quality depends on a fresh local index. Recently edited notes may require `check-changes`, `index-health`, or a rerun after background indexing catches up.134- Entity tools require the optional layered graph database; without it, use hybrid search, exact search, related notes, or bridges instead.135136## Credits137138Fork of [RafalWilinski/mcp-apple-notes](https://github.com/RafalWilinski/mcp-apple-notes);139this fork reads SQLite + protobuf directly and adds bridges, entities, feed, and synthesis.140Authored by [Conner K Ward](https://github.com/connerkward). License MIT.