apple-notes-reminders-mcp

macOS上でMCP（Model Context Protocol）互換クライアント（例：Claude Desktop）にApple NotesとApple Remindersを公開するMCPサーバー。

機能

サーバーは、NotesとRemindersの読み書きを行うための一連のツールを登録します。Notesツールは、ノートとフォルダの一覧表示、検索（画像添付内の認識テキス含む）、読み取り、作成、更新、移動、削除に加え、タグ、ピン留め状態、画像添付、最近削除した項目をカバーします。Remindersツールは、同等の操作に加えて、サブタスク、一括作成、完了、期限、フラグ、繰り返し、場所/早期アラーム、保存済みフィルタービュー、テンプレート、一括単語ベースのフィルターをカバーします。

Related MCP server: apple-reminders-mcp

アーキテクチャ

2つのドメインは異なるメカニズムで読み書きされます。

読み取りは可能な限りSQLiteを経由します。ノートはディスク上のNoteStoreデータベースから直接読み取られます:

~/Library/Group Containers/group.com.apple.notes/NoteStore.sqlite

データベースは一時的な場所にコピーされ、読み取り専用で開かれるため、実際のストアに触れたりロックしたりすることはありません。ノート本文は ZICNOTEDATA.ZDATA 内のgzipされたprotobufブロブとして保存されています。デコーダーはこれを解凍し、決定論的にprotobuf構造を辿ってテキストと書式メタデータを抽出します。

書き込みはAppleScript（osascript）を経由します。NoteStoreデータベースはNotes.appが所有しており、外部から安全に書き込むことはできないため、作成/更新/削除/移動操作はAppleScriptを介してNotes.appに委任されます。ReminderのサブタスクもAppleScriptを使用します。これはパブリックなEventKit APIでは公開されていないためです。

ノート本文のデコード

ノート本文を正しく読み取ることは、このプロジェクトの微妙な部分です。本文はプレーンテキストではなく、gzipされたブロブ内のprotobufメッセージです。デコーダーは:

1. ZDATA を解凍し、決定論的にノートテキストメッセージ（document → field 2 → field 3）に移動し、テキスト文字列（field 2）を読み取ります。これは、以前のヒューリスティックな方法（「最もクリーンな」文字列候補をスキャンし、チェックリストを含むノートで破損したバイナリを返していた）を置き換えました。

2. 繰り返されるスパンごとの段落メタデータをウォークして、チェックリスト項目とその完了/未完了状態を検出し、チェック済み項目には - [x] 、未チェック項目には - [ ] を前置します。

正確性のために重要な2つの詳細:

• Varintは、<< 演算子ではなく乗算（* 2 ** shift）で累積されます。JavaScriptのビットシフトは32ビットに切り詰められ、大きなオフセットを破損するためです。

• スパン長は、Appleの保存方法に合わせてUTF-16コード単位で測定されるため、テキストにマルチバイト文字や絵文字が含まれていても、チェックリストマーカーが正しく位置合わせされます。

何らかの理由でSQLiteデコードが失敗した場合、notes_get はAppleScriptを介してノート本文を読み取るフォールバックを行います。これによりクリーンなテキストが返されますが、チェックボックスの状態は復元できません（AppleのAppleScript body プロパティはそれをエンコードしていません）。

添付ファイル

画像添付ファイルは、ZICCLOUDSYNCINGOBJECT の ICAttachment/ICMedia 行から読み取られます（動的に Z_PRIMARYKEY/Z_ENT を介して解決され、ハードコードされません。数値エンティティIDや ZACCOUNT*/ZPARENT 列名はmacOSバージョン間で変わるためです）。実際のファイルはディスク上にあります:

~/Library/Group Containers/group.com.apple.notes/Accounts/{account}/Media/{media id}/{generation}/{filename}

notes_get は各添付ファイルのID、ファイル名、タイプ、解決されたファイルパス、認識されたOCRテキストを返します。notes_get_attachment は画像添付ファイルをMCP画像コンテンツブロックとして取得します。notes_search はOCRテキストを検索コーパスに組み込むため、スクリーンショット内にのみ表示されるテキストも検索可能です。添付ファイルの追加はサポートされていません — 以下の「既知の制限」を参照してください。

Remindersの flagged とその他のAppleScript専用読み取り

EventKitのパブリックAPIには flagged プロパティがないため、すべてAppleScriptを介して読み書きされ、EventKit由来の Reminder オブジェクトにIDでマージされます。ライブラリ全体のフラグ付きスキャンは比較的遅い（AppleScriptのプロパティごとのIPCオーバーヘッド）ため、reminders_list/reminders_search は単一のリストにスコープされた場合のみ flagged を含みます。すべてのリストにわたって必要な場合は、明示的な flagged フィルターを付けて reminders_query_where/reminders_view を使用してください。

キャッシュ

notesStore.ts は、開いているSQLite接続、検出されたスキーマ、各ノートのデコード済み本文をキャッシュし、すべての呼び出しでソースファイル（およびその -wal/-shm サイドカー）のmtimeを比較して無効化します。実際のNoteStoreへの書き込みは常にキャッシュを破棄するため、これは純粋なパフォーマンス上の利点であり、古さのリスクはありません。デコード済み本文はさらに (Z_PK, 修正日) でキー付けされるため、編集されたノートは古いキャッシュヒットではなく新しいキャッシュエントリを取得します。

要件とアクセス許可

• macOS（macOS 26 / Tahoeでテスト済み）

• Node.js 18+（SQLiteアクセスに better-sqlite3 を使用）

• Notes.appとReminders.appがセットアップされ、アカウントにサインインしていること

• 自動化のアクセス許可: ホストアプリケーション（例：Claude Desktop）がNotesとRemindersを制御できるようにする必要があります — macOSは初回使用時にプロンプトを表示するか、「システム設定 › プライバシーとセキュリティ › 自動化」で許可します

• フルディスクアクセス: ホストアプリケーションが ~/Library/Group Containers/group.com.apple.notes/NoteStore.sqlite のNoteStoreデータベースを読み取るために必要 — 「システム設定 › プライバシーとセキュリティ › フルディスクアクセス」で許可します

macOSバージョンに関する注意

ZICCLOUDSYNCINGOBJECT 内の列名と数値エンティティIDは、macOS/Notes.appのバージョン間で変化します（例：ZACCOUNT1 から ZACCOUNT8 まで、すべて異なるシステムで実際のフォルダ→アカウント外部キーとして確認されており、ICAccount/ICAttachment/ICMedia の Z_ENT 値は安定していません）。notesStore.ts の detectSchema() は、これらをハードコードするのではなく、キャッシュミスのたびに再検出します — 新しい列名をハードコードする前に、そこにあるコメントを参照してください。これはmacOS 26 (Tahoe) に対して開発およびテストされました。検出ロジックは古いバージョンでも動作するように記述されていますが、それらに対して検証されていません。

インストール

npm install
npm run build

実行

npm start

または、クライアントの設定で dist/index.js をMCPサーバーコマンドとして登録します。

プロジェクト構成

src/
  index.ts        MCP server + tool registrations
  notes.ts        Notes tool implementations (SQLite reads, AppleScript writes)
  notesStore.ts   NoteStore SQLite access + protobuf body decoder
  reminders.ts    Reminders tool implementations + local template/saved-view storage
  applescript.ts  Shared runAppleScript() helper (argv-only, never string-spliced)
  markdown.ts     Markdown -> Notes-compatible HTML converter
swift/
  reminders-daemon.swift  Persistent EventKit daemon (NDJSON over stdio)
scripts/
  test-phase2.mjs           Protobuf/checklist decoder tests (+ pinned full-pipeline fixtures)
  test-markdown.mjs         Markdown -> HTML converter tests
  test-schema-detection.mjs Schema-detection sanity checks against the live DB
dist/             Compiled output (generated by `npm run build`)

Reminderテンプレートと保存済みフィルタービュー（reminders_save_template、reminders_save_view）は ~/.apple-notes-reminders-mcp/ の下にJSONとして保存されます — EventKit自体にそのような概念がないため、これらに対するサーバー側のデータベースはありません。

アクセス許可とプライバシーに関する注意

すべての読み取りは、ローカルのNoteStoreデータベースの一時コピーに対してローカルで行われます。サーバー自体によってデバイス外に送信されるものはありません。サーバーは、ユーザーが自身のNotesとRemindersに対して既に持っているのと同じアクセス権を必要とします。

テスト

npm run build && node scripts/test-phase2.mjs           # protobuf/checklist decoder
npm run build && node scripts/test-markdown.mjs          # markdown -> Notes-HTML converter
npm run build && node scripts/test-schema-detection.mjs  # schema detection sanity (live DB)

test-markdown.mjs は完全に決定論的です。test-phase2.mjs の単体テストセクション（varintの安全性、チェックリストのエッジケース、ピン留めされたフルパイプラインフィクスチャ）は自己完結型です。その最後の「Real DB notes」セクションと test-schema-detection.mjs のすべては、実際のライブのNotesデータベースを読み取り、フルディスクアクセスと実際のノートデータが存在する場合にのみパスします — 原作者以外のマシンでは失敗/エラーが予想されます（test-phase2.mjs のDBセクションは、そのライブラリにのみ存在するノートIDを具体的に参照しています）。

既知の制限

• フォルダの再親化は実装されていません。 Notes.appのAppleScript move <folder> to <folder> は信頼性が低いことがライブで確認されています — 断続的にエラー（item N of every folder kan niet worden opgevraagd）をスローしたり、何もせずに終了したりします。フォルダ参照が folder id、whose フィルター、手動スキャンのいずれから来ても同様です。フォルダの名前変更と削除は信頼性が高く実装されています。1つのフォルダを別のフォルダの下に再親化することは、予測不能に失敗するツールを出荷するよりはましなので、実装されていません。ネストされたフォルダ（このサーバーではなくNotes.app UIで作成されたもの）の名前変更/削除はサポートされています — 完全な "Parent/Child" パスを渡してください。

• このサーバーを介して添付ファイルを追加する方法はありません。 添付ファイルの読み取りは完全にサポートされています（上記参照）。追加するにはNotes.app UIが必要です — Shortcuts-CLIベースのブリッジが調査されましたが（shortcuts run <name> -i <path>）、ゼロセットアップツールとしては実行不可能であることがわかりました。正確に1つの入力ファイルを受け入れ、ターゲットノートを渡す方法がなく、shortcuts CLIは既存のショートカットのみを実行でき、作成はできません。完全な説明については notes.ts の上部にあるコメントを参照してください。

• 音声トランスクリプトは表示されません。 画像添付からのOCRテキストは表示されます（notes_get、notes_search）。データベースには音声トランスクリプトのような形状の列（ZTEMPORARYTRANSCRIPTDATA）もありますが、不透明なブロブであり、その形式をリバースエンジニアリングするための音声添付ファイルが利用できませんでした — 実際のフィクスチャデータを持つ将来のコントリビューターのために残されています。

• 削除されたフォルダが notes_list_folders から消えるまでに1分以上かかることがあります。 ライブで確認済み：削除自体はNotes.appで即座に行われ（AppleScriptにも即座に表示されます）、SQLite行のソフトデリートフラグは60秒以上遅れることがあり、iCloud同期の往復を待っているように見えます — 他の場所での名前変更/作成で通常見られる約5秒のSQLite遅延よりもはるかに長いです。これはこのサーバーでは短縮できません。キャッシュのバグのように見えるものを追跡する人のために notesStore.ts に文書化されています。

• 「スマートフォルダ」（PLANの元の表現）は、Remindersにあるような一般的なNotes.app機能としては実際には存在しません — DBの ZFOLDERTYPE=1 は、組み込みの「最近削除した項目」フォルダと通常のフォルダを区別するだけです。そのフラグに対する読み取り専用サポートは存在します（notes_list_folders の isSmartFolder）。タグベースのグループ化（notes_list_tags）が、Notesの「保存済みスマートリスト」に近い類似物です。

• Remindersの「リストセクション」（新しいReminders.appのグループ化機能）は読み取られません — EventKitはそれらを公開しておらず、そうするにはReminders自体の別個のディスク上のストアをリバースエンジニアリングする必要があり、今回は試みられませんでした。

ツール

Notes

リマインダー