Apple Notes

MCP Apple Notes

mcp-apple-notes は、自分の Apple Notes 全体を対象にしたセマンティック検索と関連性の発見を行う MCP サーバーです。ハイブリッド検索、Swanson-ABC ブリッジ、エンティティスレッド、これまでに書いたすべての内容を対象にした出典付きの統合を提供します。

蓄積された大量のメモを横断します。セマンティック検索と BM25 のハイブリッド検索、意外な関連性をつなぐブリッジ、エンティティスレッド、関連メモ、そして Apple Notes に書いたすべての内容に基づく統合を利用できます。埋め込み、検索、BM25、クラスタリング、ブリッジはデバイス上で実行されます。LLM を呼び出すのは統合の生成のみです（LM Studio／Ollama を使ったローカル実行、または OpenAI を使ったクラウド実行を選択できます）。Model Context Protocol（MCP）を基盤としています。

RafalWilinski/mcp-apple-notes からフォークしました。このフォークは SQLite ストアと protobuf を直接読み取り、ブリッジ、エンティティ、フィード、統合機能を追加しています。

Claude Code プラグインとしてインストール

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

MCP サーバーを登録し、apple-notes-search エージェントスキルをバンドルします。または、MCP サーバーを手動でインストールしてください。下記のインストールを参照してください（macOS、bun、フルディスクアクセスが必要です）。

ほかの MCP Notes サーバーは、大規模なデータで動作しなくなります。 JXA（AppleScript 自動化）を使ってメモを1件ずつ読み取るため、50件なら問題ありませんが、500件以上では実用になりません。メモが1,800件ある場合、JXA では内容の取得だけで約49分かかります。macOS Sequoia ではさらに深刻です。Apple はバンドル ID のないプロセスに対するオートメーションのアクセス許可をひそかに拒否するため、JXA ベースのサーバーはまったく動作しません。このフォークは SQLite データベースを直接読み取り、protobuf blob をデコードして実際のメモ本文を取得し、1,800件のメモを5秒以内にインデックス化します。

比較

機能	このフォーク	RafalWilinski（ベース）	disco-trooper	sirmews	dhravya
メモへのアクセス	SQLite（直接）	JXA	JXA	SQLite	JXA
1,800件のメモの取得	約430ms	約49分（推定）	約49分（推定）	高速	低速
Sequoia との互換性	✅	⚠️ JXA が拒否される	⚠️ JXA が拒否される	✅	⚠️
コンテンツの品質	protobuf をデコード	生の HTML	生の HTML	部分的	生データ
セマンティック検索	✅	✅	✅	❌	❌
検索時の自動再インデックス	✅	❌	❌	❌	❌
フォルダーを考慮した検索	✅ フルパス	❌	✅	✅	✅
メモのチャンク分割	✅ 1,500文字	❌	✅	❌	❌
再ランキング（RRF × タイトル × 新しさ）	✅	RRF のみ	RRF のみ	❌	❌
ノンブロッキングのインデックス UI	✅ 進行状況をリアルタイム表示	❌	❌	❌	❌
増分インデックス化	✅	❌	✅	❌	❌
既存メモの更新	✅	❌	✅	❌	❌
タグとウィキリンク	✅	❌	❌	❌	❌
関連メモ	✅ 複数のシグナルを使用	❌	❌	❌	❌

macOS Sequoia の JXA：バンドル ID のないプロセスは、オートメーションのアクセス許可をひそかに自動拒否されます。このフォークは SQLite を直接読み取ります。

機能

• 🔍 all-MiniLM-L6-v2 によるセマンティック検索。埋め込みはデバイス上で実行
• 📝 BM25 全文検索を Reciprocal Rank Fusion で統合
• 🧠 再ランキング：RRF × title_boost × recency_factor
• 📂 フォルダー階層全体に対応 — 任意のパス要素で絞り込み
• 🕐 自動再インデックス：検索のたびに約1msで変更を検出し、メモが変更されていればバックグラウンドでインデックス処理を1つだけ開始します（シングルフライト）。検索自体はインデックス処理の完了を待ちません
• ✂️ 長いメモを1,500文字単位でチャンク分割
• 🍎 SQLite と protobuf を直接デコード — 読みにくい HTML ではなく、実際のメモ本文を取得
• 🏃‍♂️ デバイス上で動作 — 埋め込み、検索、BM25、クラスタリング、ブリッジは API キー不要でローカル実行されます。任意の統合の生成のみ、LLM を呼び出します（LM Studio／Ollama を使ったローカル実行、または OpenAI を使ったクラウド実行を選択できます）

ローカル Web アプリ — 検索だけでなく、つながりの発見と統合も

サーバーを直接起動し、ブラウザー UI を開きます。MCP クライアントは不要です。

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

検索から意味の理解へと段階的に進む、6 つのモードがあります。

• Feed（デフォルト）— 3 種類のつながりを組み合わせた、ランキング形式のエビデンス優先ストリームです。ブリッジ（B を介した A ↔ C。B から抽出したつなぎとなるフレーズをプレーンテキストのエビデンスとして表示）、抽象化ペア（~/.mcp-apple-notes/consolidated.jsonl にある LLM 統合済みの抽象化に基づき、根底にある同じ展開をする 2 件のノート）、エンティティスレッド（エンティティグラフをもとに「Y 個のフォルダーにある X 件のノートで Z に言及」）です。すべての項目にエビデンスをプレーンテキストで表示します。項目に 👍／👎 を付けるとランキングが調整されます。依存関係のない小規模なオンラインロジスティック回帰（純粋な TS）が、投票のたびに SGD を数ステップ実行します。投票は（項目の特徴ベクトルとともに）~/.mcp-apple-notes/votes.jsonl に追記され、起動時に再生されるため、再起動後もランキングが維持されます。多様性の制約：同じ種類の項目が 3 件以上連続しないこと、20 件のページ内で同じノートを 3 回以上表示しないこと。「さらに表示」でページを切り替えます。エンドポイント：GET /api/feed?offset=&limit=, POST /api/vote {id, vote: 1|-1}。
• Search — セマンティック検索と BM25 検索を組み合わせたハイブリッド検索です。クエリのハイライト表示とフォルダーフィルターを備えた、論文をテーマにした UI で利用できます。
• Map — すべてのノートを対象としたトピックマップです。埋め込みを球面 k-means でクラスタリングし（TF-IDF でラベル付け）、PCA で 2D に投影します。ノートにカーソルを合わせると 近傍レンズ が表示されます。意味的に最も近いノートへ線が引かれます。これらの線はクラスタをまたぐことが多く、つながりを見つける手がかりになります。エンドポイント：GET /api/clusters?k=。
• Synthesize — 「これまでに書いたもの全体を通して、X についてどう考えているか？」 クエリ拡張 → 関連性で絞り込んだ検索（新しさによる偏りなし）→ MMR による多様化を行い、LLM がソースノートを示すインライン引用 [n] 付きの根拠ある回答を生成します。出典情報は生成後に検証されます。エンドポイント：GET /api/synthesize?q=。
• Bridges — 自分のノートを対象とした Swanson-ABC 探索です。直接は類似していないものの、共有ブリッジノート B には強く類似する (A, C) のペアを見つけます。コーパス内のつながりが中間項を介してのみ見つかる場合に有効です。埋め込みに対する純粋な算術処理です（スコア = sim(A,B)·sim(B,C)·(1−sim(A,C))。異なるフォルダーにあること、共有タグや Wiki リンクがないこと、しきい値は自動調整されます。ハブにペナルティを与える選択方式により、1 つのノートが一覧を独占するのを防ぎます）。LLM 不要、$0。エンドポイント：GET /api/bridges?limit=40。
• Entities — 「Mercedes について、ほかにどこで話しているか？」 ランキング形式のエンティティチップ（人物、組織、概念）から、言及の重みに基づいて該当するノートを表示します。オプションの sqlite グラフ DB を読み込みます（下記参照）。エンドポイント：GET /api/entities?q=&limit=, GET /api/entity-notes?entity=。

事前計算済みディスクキャッシュ（ブリッジとマップを即時表示）

ブリッジのマイニング（埋め込みに約 2 分）とクラスタリングは一度だけ計算され、コーパスのフィンガープリント（ノート数 + 最終更新日）をキーとして保存されます。

• ~/.mcp-apple-notes/bridges_cache.json — マイニング済みブリッジ全体
• ~/.mcp-apple-notes/clusters_cache.json — k ごとのクラスタリング結果

キャッシュが新鮮な場合は、ディスクから即座に提供されます（<300ms）。古くなっている場合（ノートが変更された場合）も、古いキャッシュを即座に提供し、UI に「再計算中…」のピルを表示する間に、バックグラウンドジョブを 1 つだけ（シングルフライト）実行して更新します。キャッシュがない場合は、その場で一度だけ計算します。

統合機能を有効にする（LLM が必要）

埋め込み、検索、クラスタリング、ブリッジ、エンティティの処理はすべてローカルで実行されます。LLM が必要なのは統合結果の生成のみです。ノートをプライベートに保つには、ローカルの OpenAI 互換サーバーを指定してください。

# 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).

エンティティグラフ（任意）

エンティティレイヤーは ~/.mcp-apple-notes/layered_graph.db を読み込みます（LAYERED_DB で変更可能）。これは、関連する exp-notes-indexing ベンチマークハーネスの layered_graph.py が生成する、通常の sqlite ファイルです。追加の依存関係はありません（bun には bun:sqlite が同梱されています）。ファイルがない場合、エンティティツールとタブに生成方法が表示されます。

インストール

1. クローンしてインストールします。

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

2. システム設定で bun（~/.bun/bin/bun）にフルディスクアクセスを許可します。

3. claude_desktop_config.json に追加します。

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

4. Claude Desktop を再起動し、「Apple Notes をインデックス化して」と依頼します。

Claude Code / CLI への登録

// .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"]
    }
  }
}

同じブリッジ／エンティティツールが、ローカルアプリ（bun index.ts → http://localhost:3741/）のウェブ UI タブでも使われます。エンティティグラフ DB は任意で、exp-notes-indexing ベンチマークハーネスによって生成されます。

ツール

ツール	説明
index-notes	ライブ進捗 UI を備えたバックグラウンドでのインデックス化
search-notes	セマンティック検索と FTS 検索。folder、modifiedAfter、modifiedBefore は任意です
find-notes	完全一致の部分文字列検索（Apple Notes の標準機能と同様）。folder、日付範囲は任意です
get-note	タイトルでノート全体を取得。完全一致しない場合はあいまい検索にフォールバックします
list-notes	更新日時順にノートを一覧表示。folder、日付範囲、limit は任意です
list-folders	ノート数付きですべてのフォルダーを一覧表示
list-tags	すべてのノートにある #hashtags を頻度順に一覧表示
search-by-tag	特定のハッシュタグを含むノートを検索
related-notes	共通タグ、[[wikilinks]]、ベクトル類似度に基づいて関連ノートを検索
bridge-notes	Swanson-ABC ブリッジ：共通の中間ノートを介してつながる、類似していないノートのペア。folder、limit は任意です
feed	ランク付けされたエビデンス優先のつながりフィード（ブリッジ＋抽象化ペア＋エンティティスレッド）を JSON で返します。limit は任意です
entity-notes	エンティティ（例：「Mercedes」）に言及しているノートを、言及の重み順に表示します。任意のエンティティグラフ DB が必要です
list-entities	言及数順にエンティティを一覧表示。部分文字列による query、limit は任意です
get-tables	ノートからパイプ区切り／タブ区切りの表を抽出
create-note	ノートを作成
update-note	既存のノートを編集
check-changes	最後のインデックス化以降にノートが変更されたか確認（再インデックス化は行いません）
index-health	同期状態、最後にインデックス化した日時、ノート数

検索とランキング

検索のたびに変更を検出します（約1ms）。ノートが変更されている場合、バックグラウンドで差分インデックス化ジョブが1つ起動します（同時実行は1つのみ。重複した起動要求は破棄されます）。検索は現在のインデックスからすぐに結果を返し、ジョブの完了後に結果が追いつきます。最後にインデックス化した時点のウォーターマークは、再起動後も ~/.mcp-apple-notes/index_state.json に保持されます。変更検出では、タイトルごとの更新日時の 集合 を比較します（Apple Notes ではタイトルは重複します。「TODO」が10件ある場合など、タイトルから単一の日付へのマップでは重複を解消できません）。

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

時間に関するクエリ（recent、latest、today）では、時間的な新しさの半減期を自動的に1日に切り替え、重みを70%にします。通常のクエリでは半減期を90日、重みを10%とし、関連性を優先します。

ベンチマーク

ノート1,806件、Apple Silicon：

方法	所要時間	本文を含む
JXA メタデータのみ	4,463ms	いいえ
本文を含む JXA	約49分	はい
SQLite 直接アクセス	430ms	はい

トラブルシューティング

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

権限エラー → システム設定 → プライバシーとセキュリティで、bun（~/.bun/bin/bun）にフルディスクアクセスが許可されていることを確認してください。

---

🧭 ckw-skills — Conner K. Ward の Claude Code スキルと MCP サーバーのコレクションの一部です。