Apple Notes Mcp

apple-notes-mcp

セマンティック検索と CRUD 操作に対応した Apple Notes 用 MCP サーバーです。Claude は自然言語を通じて、Apple Notes の検索、読み取り、作成、更新、管理を行えます。

特長

• チャンクベースの検索 - 長いノートをチャンクに分割し、正確にマッチングします
• クエリのキャッシュ - 繰り返しの検索を 60 倍高速化します
• ナレッジグラフ - タグ、リンク、関連するノートを見つけます
• ハイブリッド検索 - Reciprocal Rank Fusion によるベクトル検索とキーワード検索
• セマンティック検索 - キーワードではなく意味からノートを見つけます
• 完全な CRUD - ノートの作成、読み取り、更新、削除、移動に対応します
• 増分インデックス作成 - 変更されたノートのみを再埋め込みします
• バックグラウンドインデックスジョブ - 進行状況をポーリングできる、非同期の全件／増分インデックス作成
• デュアル埋め込み - ローカルの HuggingFace または OpenRouter API

バージョン 1.9.0 の新機能

• 大規模ライブラリのインデックス作成 - Fetch がノートのプロパティをまとめてバッチ取得するため、数千件のノートでも停止せずにインデックス作成が完了します
• 堅牢な取得処理 - ロック中または同期中のノートはバッチごとに再試行され、実行全体を失敗させずにレポートを出してスキップします
• キャンセル可能な読み取り - Notes の長時間読み取りはタイムアウトし（JXA_TIMEOUT_MS）、キャンセルすると取得処理が実際に停止します

バージョン 1.8.1 の新機能

• list-notes のフォルダー絞り込みを高速化 - list-notes はすべてのノートを先に走査せず、指定されたフォルダーのみを照会するようになりました
• 重複するフォルダー名の正確性 - フォルダーの絞り込みで、アカウントをまたいで一致するフォルダーを集約するようになりました
• 大規模なライブラリでのパフォーマンス - フォルダーを指定した一覧表示が、大規模なノートライブラリで大幅に高速化しました

インストール

npm（推奨）

npm install -g @disco_trooper/apple-notes-mcp
apple-notes-mcp

セットアップウィザードでは、次の手順を案内します。

1. 埋め込みプロバイダー（ローカルまたは OpenRouter）を選択します
2. 必要に応じて API キーを設定します
3. Claude Code との連携を設定します
4. ノートをインデックス化します

ソースからインストール

git clone https://github.com/disco-trooper/apple-notes-mcp.git
cd apple-notes-mcp
bun install
bun run start

必要条件

• macOS（JXA を介して Apple Notes を使用します）
• Bun ランタイム
• ノートが保存された Apple Notes アプリ

クイックスタート

インストール後にコマンドを実行します。

apple-notes-mcp

初回実行時にセットアップウィザードが自動的に起動します。セットアップ後、MCP ツールを使用するには Claude Code を再起動してください。

設定

設定は ~/.apple-notes-mcp/.env に保存されます。

変数	説明	デフォルト
OPENROUTER_API_KEY	OpenRouter API キー（クラウド埋め込みを有効にします）	-
EMBEDDING_MODEL	モデル名（ローカルまたは OpenRouter）	Xenova/multilingual-e5-small
EMBEDDING_DIMS	埋め込みの次元数	4096
READONLY_MODE	すべての書き込み操作をブロックします	false
INDEX_TTL	検索時の自動更新間隔（秒単位。未設定の場合は無効）	-
SEARCH_REFRESH_TIMEOUT_MS	古いインデックスを使用する前に、検索が更新を待つ最大時間	2000
INDEX_JOB_RETENTION_SECONDS	完了または失敗したインデックスジョブを照会可能な状態で保持する期間	3600
EMBEDDING_BATCH_SIZE	埋め込み生成のバッチサイズ	50
NOTES_FETCH_BATCH_SIZE	Notes の取得処理のバッチサイズ	100
JXA_TIMEOUT_MS	Notes の単一読み取りにかける最大時間（ミリ秒）	120000
DEBUG	デバッグログを有効にします	false

検索の自動更新ポリシー

• search-notes は、リクエストごとに強制的に更新するわけではありません。
• INDEX_TTL が設定されていない場合、自動更新は無効になり、現在のインデックスを使用して検索します。
• INDEX_TTL が設定されている場合、TTL の期限切れ後にのみ更新を実行します。
• 更新に失敗するか、SEARCH_REFRESH_TIMEOUT_MS より時間がかかる場合、検索はタイムアウトせず、古いインデックスの結果にフォールバックします。

再設定するには：

apple-notes-mcp setup
# or from source:
bun run setup

埋め込みプロバイダー

ローカル（デフォルト）：HuggingFace Transformers と Xenova/multilingual-e5-small を使用します。無料でローカルに実行でき、ダウンロードサイズは約 200MB です。

OpenRouter：クラウド API を使用します。高速で、ローカルリソースは不要ですが、openrouter.ai から API キーを取得する必要があります。

モデルの比較については、docs/models.md をご覧ください。

ツール

検索と探索

search-notes

ベクトル検索と全文検索を組み合わせたハイブリッド検索です。

query: "meeting notes from last week"
folder: "Work"           # optional, filter by folder
limit: 10                # default: 20
mode: "hybrid"           # hybrid, keyword, or semantic
include_content: false   # include full content vs preview

list-notes

並べ替えや絞り込みを指定してノートを一覧表示します。パラメーターを指定しない場合は、インデックスの統計情報を表示します。

sort_by: "modified"      # created, modified, or title (default: modified)
order: "desc"            # asc or desc (default: desc)
limit: 10                # max notes to return (1-100)
folder: "Work"           # filter by folder (case-insensitive)

folder を指定すると、サーバーは Apple Notes から該当するフォルダーのみを取得します。これにより、ボルトに数百件のノートがあっても、フォルダーを指定したリクエストを高速に処理できます。

例：

• 新しいノートを 5 件取得：{ sort_by: "created", order: "desc", limit: 5 }
• 最近更新されたノート：{ sort_by: "modified", limit: 10 }
• フォルダー内をアルファベット順に表示：{ sort_by: "title", order: "asc", folder: "Projects" }

list-folders

Apple Notes のすべてのフォルダーを一覧表示します。

get-note

タイトルを指定してノートの内容を取得します。

title: "My Note"          # or "Work/My Note" for disambiguation
include_html: false       # include raw HTML (default: false)

get-tables

ノートから構造化されたテーブルデータを抽出します。

title: "My Note"

戻り値：

{
  "tableCount": 2,
  "tables": [{
    "index": 0,
    "rows": [["Header1", "Header2"], ["Val1", "Val2"]],
    "formatting": [[{"bold": true}, {"bold": true}], ...]
  }]
}

インデックス作成

index-notes

セマンティック検索用にノートをインデックス化します。

mode: "incremental"       # incremental (default) or full
force: false              # force reindex even if TTL hasn't expired
background: false         # optional; defaults to false (synchronous mode)

長いノートの検索精度を高めるチャンクインデックスを作成するには、mode: "full" を使用します。最初の全件インデックス作成ではチャンクを生成するため時間がかかりますが、以降の検索は高速に実行されます。

大規模なボルトでは、バックグラウンドでのインデックス作成を推奨します。

start-index-job

mode: "full"               # full or incremental

id、status、progress を含むジョブのスナップショットを返します。 取得、埋め込み、永続化の各フェーズで、より細かいステップ単位で進捗が更新されます。

get-index-job

job_id: "<job-id>"

ステータスが completed、failed、または cancelled になるまでポーリングします。 移行中のステータスとして cancelling が表示される場合があります。

list-index-jobs

limit: 10                  # optional, 1-50

cancel-index-job

job_id: "<job-id>"

実行中のジョブに対し、可能な範囲でキャンセルを要求します。キャンセルは協調的に行われます。

• 時間のかかるステップは、キャンセルチェックポイントに到達する必要があります。
• 作業の一部が残る場合があります。
• 現在のジョブが cancelled になってから、新しいジョブを開始してください。

reindex-note

手動で編集した後、単一のノートを再インデックス化します。

title: "My Note"

CRUD 操作

create-note

Apple Notes にノートを作成します。

title: "New Note"
content: "# Heading\n\nMarkdown content..."
folder: "Work"            # optional, defaults to Notes

作成、更新、削除、移動の後、サーバーはベストエフォートモードでベクトルインデックスとチャンクインデックスを自動同期します。 同期が一部失敗した場合、ツールの応答に index sync warning が含まれます。reindex-note または index-notes を実行してください。

update-note

既存のノートを更新します。

title: "My Note"
content: "Updated markdown content..."
reindex: true             # re-embed after update (default: true)

delete-note

ノートを削除します（確認が必要です）。

title: "My Note"
confirm: true             # must be true to delete

move-note

ノートを別のフォルダーに移動します。

title: "My Note"
folder: "Archive"

batch-delete

複数のノートを一度に削除します。

titles: ["Note 1", "Note 2"]  # OR folder: "Old Project"
confirm: true                 # required for safety

batch-move

複数のノートを指定したフォルダーに移動します。

titles: ["Note 1", "Note 2"]  # OR sourceFolder: "Old"
targetFolder: "Archive"       # required

インデックス管理

purge-index

インデックス化されたすべてのデータを消去します。埋め込みモデルを切り替える場合や、インデックスの破損を修復する場合に使用します。

confirm: true   # required for safety

消去後、インデックスを再構築するには index-notes を実行してください。

ナレッジグラフ

list-tags

すべてのタグを出現回数とともに一覧表示します。

search-by-tag

特定のタグが付いたノートを検索します。

tag: "project"
folder: "Work"    # optional
limit: 20         # default: 20

related-notes

元のノートに関連するノートを検索します。

title: "My Note"
types: ["tag", "link", "similar"]  # default: all
limit: 10                          # default: 10

export-graph

可視化用にナレッジグラフをエクスポートします。

format: "json"     # json or graphml
folder: "Work"     # optional filter

対応フォーマット：

• json - カスタム可視化用（D3.js、ウェブアプリ）
• graphml - 専門ツール用（Gephi、yEd、Cytoscape）

Claude Code のセットアップ

自動（推奨）

セットアップウィザードが apple-notes-mcp を Claude Code に自動で追加します。インストール後に apple-notes-mcp を実行してください。

マニュアル

~/.claude.json に追加します：

npm でインストールする場合：

{
  "mcpServers": {
    "apple-notes": {
      "command": "apple-notes-mcp",
      "args": [],
      "env": {}
    }
  }
}

ソースからインストールする場合：

{
  "mcpServers": {
    "apple-notes": {
      "command": "bun",
      "args": ["run", "/path/to/apple-notes-mcp/src/index.ts"],
      "env": {}
    }
  }
}

使用例

セットアップ後、Claude に自然言語で指示します：

• 「プロジェクトのアイデアについてメモを検索して」
• 「仕事」フォルダーに「会議メモ」という名前のメモを作成して
• 「休暇の計画についてのメモには何が書いてある？」
• 「古いプロジェクト」のメモを「アーカイブ」に移動して
• 「メモをインデックス化して」（Apple Notes にメモを追加した後）

トラブルシューティング

「Note not found」

同じ名前のメモが複数ある場合は、Folder/Note Title の形式でフルパスを指定してください。

初回の検索が遅い

ローカルの埋め込みモデルは、初回使用時にダウンロードされます（約200MB）。2回目以降の検索は高速に実行されます。

「READONLY_MODE is enabled」

書き込み操作を有効にするには、.env で READONLY_MODE=false に設定してください。

検索結果にメモが表示されない

検索インデックスを更新するには、index-notes を実行してください。差分更新で変更が反映されない場合は、mode: full を使用してください。

「iCloud account not available」／Can't get account "iCloud"

このエラーは、search_notes ツールと Keywords 引数を使用する別の Apple Notes MCP 実装で発生します。

このプロジェクトでは以下を使用します：

• ツール：search-notes
• 引数：query

クライアントが Keywords を指定して search_notes を呼び出す場合は、MCP 設定を apple-notes-mcp に変更し、クライアントを再起動してください。

JXA エラー

Apple Notes が起動していて、メモが含まれていることを確認してください。プロンプトが表示されたら、オートメーションのアクセス許可を付与してください。

「JSON Parse error: Unexpected identifier undefined」

通常、これはインデックス作成プロセスのメモリが不足したことを意味します。次を試してください：

1. メモリを確保するため、ほかのアプリケーションを終了する
2. メモリ使用量を減らすため、.env で EMBEDDING_BATCH_SIZE=25 に設定する
3. Apple Notes アプリを再起動する
4. index-notes を再度実行する

インデックス作成中にスキップされたメモ

次のようなメモはスキップされる場合があります：

• ロック中 - インデックスに含める場合は、Apple Notes でロックを解除してください
• 同期中 - iCloud の同期完了を待ってから、インデックスを再作成してください
• 破損 - 内容を新しいメモにコピーしてから、古いメモを削除してください

インデックス作成ツールは、スキップされたメモを報告し、残りのメモの処理を続行します。

開発

# Type check
bun run check

# Run tests
bun run test

# Run with coverage
bun run test:coverage

# Run with debug logging
DEBUG=true bun run start

# Watch mode
bun run dev

貢献

プルリクエストを歓迎します！次の点にご協力ください：

• 提出前に bun run check を実行する
• 新機能にはテストを追加する
• 必要に応じてドキュメントを更新する

ライセンス

MIT