MCP Apple Notes

mcp-apple-notes is an MCP server for semantic search and connection-discovery across your own Apple Notes — hybrid search, Swanson-ABC bridges, entity threads, and cited synthesis over everything you've written.

It traverses your accumulated mass of notes: semantic + BM25 hybrid search, non-obvious bridge connections, entity threads, related-notes, and grounded synthesis across everything you've ever written in Apple Notes. Embeddings, search, BM25, clustering, and bridges run on-device; only synthesis generation calls an LLM (local via LM Studio/Ollama, or cloud via OpenAI — your choice). Built on the Model Context Protocol (MCP).

Forked from RafalWilinski/mcp-apple-notes — this fork reads the SQLite store + protobuf directly and adds bridges, entities, feed, and synthesis.

Install as a Claude Code plugin

Code

/plugin marketplace add connerkward/ckw-skills
/plugin install apple-notes@connerkward

This registers the MCP server and bundles the apple-notes-search agent skill. Or install the MCP server manually — see Installation below (requires macOS + bun + Full Disk Access).

Other MCP Notes servers break at scale. They use JXA (AppleScript automation) to read notes one-by-one — fine for 50 notes, unusable at 500+. At 1,800 notes, JXA takes ~49 minutes just to fetch content. On macOS Sequoia it's worse: Apple silently denies Automation permission to processes without a bundle ID, so JXA-based servers fail entirely. This fork reads the SQLite database directly, decodes the protobuf blobs for real note text, and indexes 1,800 notes in under 5 seconds.

MCP Apple Notes

Comparison

Feature	This fork	RafalWilinski (base)	disco-trooper	sirmews	dhravya
Notes access	SQLite (direct)	JXA	JXA	SQLite	JXA
Fetch 1800 notes	~430ms	~49 min (est.)	~49 min (est.)	fast	slow
Sequoia compatible	✅	⚠️ JXA denied	⚠️ JXA denied	✅	⚠️
Content quality	Protobuf decoded	Raw HTML	Raw HTML	Partial	Raw
Semantic search	✅	✅	✅	❌	❌
Auto re-index on search	✅	❌	❌	❌	❌
Folder-aware search	✅ Full path	❌	✅	✅	✅
Note chunking	✅ 1500 chars	❌	✅	❌	❌
Re-ranking (RRF × title × recency)	✅	RRF only	RRF only	❌	❌
Non-blocking index UI	✅ Live progress	❌	❌	❌	❌
Incremental indexing	✅	❌	✅	❌	❌
Update existing notes	✅	❌	✅	❌	❌
Tags + wikilinks	✅	❌	❌	❌	❌
Related notes	✅ Multi-signal	❌	❌	❌	❌

JXA on macOS Sequoia: processes without a bundle ID are silently auto-denied Automation permission. This fork reads SQLite directly.

Features

🔍 Semantic search via all-MiniLM-L6-v2 on-device embeddings
📝 BM25 full-text search combined via Reciprocal Rank Fusion
🧠 Re-ranking: RRF × title_boost × recency_factor
📂 Full folder hierarchy — filter by any path segment
🕐 Auto re-index: every search runs ~1ms change detection and, if notes changed, kicks ONE background index job (single-flight) — search itself never blocks on indexing
✂️ 1500-char chunking for long notes
🍎 Direct SQLite + protobuf decode — real note text, not garbled HTML
🏃‍♂️ On-device — embeddings, search, BM25, clustering, and bridges run locally with no API keys; only optional synthesis generation calls an LLM (local LM Studio/Ollama, or cloud OpenAI — your choice)

Local web app — not just search, but connections & synthesis

Run the server directly and open the browser UI — no MCP client needed:

bash

bun index.ts            # → http://localhost:3741/   (also serves /mcp)

Six modes, building from retrieval toward sensemaking:

Feed (default) — one ranked, evidence-first stream mixing three connection kinds: bridges (A ↔ C via B, with the connecting phrase mined from B as plain-text evidence), abstraction pairs (two notes whose LLM-consolidated abstractions from ~/.mcp-apple-notes/consolidated.jsonl make the same underlying move), and entity threads ("X notes across Y folders mention Z", from the entity graph). Every item shows its evidence in plain text. 👍/👎 on any item tunes the ranking: a tiny online logistic regression (pure TS, no deps) takes a few SGD steps per vote; votes append to ~/.mcp-apple-notes/votes.jsonl (with the item's feature vector) and replay on boot, so the ranking survives restarts. Diversity constraints: ≤2 consecutive items of one kind, no note more than twice per page of 20; "show more" paginates. Endpoints: GET /api/feed?offset=&limit=, POST /api/vote {id, vote: 1|-1}.
Search — the hybrid semantic + BM25 search, in a paper-themed UI with query highlighting and folder filter.
Map — a topic map of every note: spherical k-means clusters (TF-IDF labels) over the embeddings, projected to 2D with PCA. Hover a note for the neighbor-lens — lines to its nearest-by-meaning notes, which often cross clusters (the connection-finding payload). Endpoint: GET /api/clusters?k=.
Synthesize — "what do I think about X across everything I've written?" Query-expansion → relevance-gated retrieval (no recency bias) → MMR diversification → an LLM writes a grounded answer with inline [n] citations back to the source notes; provenance is post-checked. Endpoint: GET /api/synthesize?q=.
Bridges — Swanson-ABC discovery over your own notes: pairs (A, C) that are not directly similar but are both strongly similar to a shared bridge note B — connections the corpus only makes through an intermediary. Pure arithmetic over the embeddings (score = sim(A,B)·sim(B,C)·(1−sim(A,C)); cross-folder, no shared tags/wikilinks; thresholds auto-relax; hub-penalized selection so no note dominates the list). No LLM, $0. Endpoint: GET /api/bridges?limit=40.
Entities — "where else do I talk about Mercedes?" Ranked entity chips (people, orgs, concepts) → the notes that mention them, by mention weight. Reads an optional sqlite graph db (see below). Endpoints: GET /api/entities?q=&limit=, GET /api/entity-notes?entity=.

Precomputed disk caches (instant bridges & map)

Bridge mining (~2 min of embedding) and clustering are computed once and persisted, keyed by a corpus fingerprint (note count + max modification date):

~/.mcp-apple-notes/bridges_cache.json — the full mined bridge pool
~/.mcp-apple-notes/clusters_cache.json — cluster output per k

Fresh cache → served from disk instantly (<300ms). Stale (notes changed) → the stale copy is served instantly with a "recomputing…" pill in the UI while ONE background job (single-flight) refreshes it. Absent → computed inline once.

Enabling synthesis (needs an LLM)

Embeddings/search/clustering/bridges/entities are fully local. Only synthesis generation needs an LLM. Point at a local OpenAI-compatible server to keep notes private:

bash

# LM Studio / Ollama (zero API cost, notes stay local):
SYNTH_BASE_URL=http://localhost:1234/v1 SYNTH_MODEL=<loaded-model> OPENAI_API_KEY=local bun index.ts
# …or real OpenAI: set a funded OPENAI_API_KEY (defaults to gpt-4o-mini).

The entity graph (optional)

The entity layer reads ~/.mcp-apple-notes/layered_graph.db (override with LAYERED_DB) — a plain sqlite file produced by the companion exp-notes-indexing benchmark harness (layered_graph.py). No extra dependencies (bun ships bun:sqlite); if the file is absent the entity tools and tab simply report how to generate it.

Installation

Clone and install:

bash

git clone https://github.com/connerkward/mcp-apple-notes
cd mcp-apple-notes
bun install

Add bun (~/.bun/bin/bun) to Full Disk Access in System Settings.
Add to claude_desktop_config.json:

config.json

{
  "mcpServers": {
    "apple-notes": {
      "command": "/Users/<YOUR_USER_NAME>/.bun/bin/bun",
      "args": ["/Users/<YOUR_USER_NAME>/mcp-apple-notes/index.ts", "--stdio"]
    }
  }
}

Restart Claude Desktop and ask: "Index my Apple Notes".

Claude Code / CLI registration

json

// .mcp.json (project) or `claude mcp add apple-notes -- bun /path/to/mcp-apple-notes/index.ts --stdio`
{
  "mcpServers": {
    "apple-notes": {
      "command": "bun",
      "args": ["/path/to/mcp-apple-notes/index.ts", "--stdio"]
    }
  }
}

The same bridges/entities tools power the web UI tabs at the local app (bun index.ts → http://localhost:3741/); the entity graph db is optional, generated by the exp-notes-indexing benchmark harness.

Tools

Tool	Description
`index-notes`	Background indexing with live progress UI
`search-notes`	Semantic + FTS search; optional `folder`, `modifiedAfter`, `modifiedBefore`
`find-notes`	Exact substring search (like Apple Notes built-in); optional `folder`, date range
`get-note`	Full note by title; fuzzy fallback on no exact match
`list-notes`	Notes sorted by recency; optional `folder`, date range, `limit`
`list-folders`	All folders with note counts
`list-tags`	All `#hashtags` across notes, sorted by frequency
`search-by-tag`	Notes containing a specific hashtag
`related-notes`	Related notes via shared tags, `[[wikilinks]]`, and vector similarity
`bridge-notes`	Swanson-ABC bridges: non-similar note pairs connected via a shared intermediary; optional `folder`, `limit`
`feed`	The ranked evidence-first connection feed (bridges + abstraction pairs + entity threads) as JSON; optional `limit`
`entity-notes`	Notes mentioning an entity (e.g. "Mercedes"), by mention weight — needs the optional entity graph db
`list-entities`	Entities ranked by mention count; optional substring `query`, `limit`
`get-tables`	Extract pipe/tab-separated tables from a note
`create-note`	Create a note
`update-note`	Edit an existing note
`check-changes`	Check if notes changed since last index (without triggering re-index)
`index-health`	Sync status, last indexed time, note count

Search & Ranking

Every search detects changes (~1ms). If notes changed, ONE background incremental index job is kicked (single-flight — duplicate triggers are dropped) and the search returns immediately from the current index; results catch up when the job lands. The last-indexed watermark persists to ~/.mcp-apple-notes/index_state.json across restarts. Change detection compares the per-title set of modification dates (Apple Notes titles are not unique — "TODO" ×10 — and a title→single-date map can never converge for duplicates).

Code

score = RRF(vector, BM25) × title_boost × recency_factor

Temporal queries (recent, latest, today) automatically shift to a 1-day recency half-life at 70% weight. Normal queries use 90-day half-life at 10% so relevance stays primary.

Benchmarks

1,806 notes, Apple Silicon:

Approach	Time	Body included
JXA metadata only	4,463ms	No
JXA with body	~49 min	Yes
SQLite direct	430ms	Yes

Troubleshooting

bash

tail -n 50 -f ~/Library/Logs/Claude/mcp-server-apple-notes.log

Permissions error → ensure bun (~/.bun/bin/bun) has Full Disk Access in System Settings → Privacy & Security.

🧭 ckw-skills — part of Conner K. Ward's collection of Claude Code skills & MCP servers.