Cupertino

日常的に使うAppleアプリにエージェントを導入しましょう。

MacにすでにあるAppleアプリ向けのMCPサーバー、そして署名済みアプリが、毎回個別にではなく一度だけ権限を付与します。MCPを話すあらゆるエージェントに対応し、単一ホスト専用ではありません。

非公式。 Appleとは提携していません。これらはMacにすでにあるアプリを操作します。

使用例

仕事の受信トレイの書き方を確認して、同じ文体でこの返信を下書きしてください。

Atlasローンチに関するメール、カレンダー、メモからすべての情報をまとめてください。まだ対応が必要な人は誰ですか？

昨日のクライアントスレッドのアクション項目を、期日付きのリマインダーに変換してください。

これらのそれぞれには制約が伴います — アカウント、日付の制限、フィルターなどです。それが、素朴な osascript 方式が74秒かかったり誤答したりする部分であり、サーバーが存在する理由です。セッションごとにモデルが再導出するのではなく、サーバーが保持します。測定結果は docs/verify.md に、代替案のコストは docs/alternatives.md にあります。

最後のものは、Remindersで書き込みゲートを開く必要があります。サーフェスごとに書き込みはオフになっており、オンに切り替えない限り、変更ツールはまったく登録されません — 書き込みがオフのエージェントは、それらの存在すら認識できません。

Related MCP server: apple-mcp

サーフェス

各サーフェスは独自のサーバーであり、独自のnpmパッケージです。したがって、ホストは必要なツールだけを読み込みます。これらは1つのバンドルと1つのフルディスクアクセス許可を共有しており、それが共存する理由そのものです — docs/distribution.md を参照してください。

クイックスタート

各サーバーはnpm上にあり、npx から直接実行されます — Claude Codeの場合、プロジェクトの隣にある .mcp.json に:

{
  "mcpServers": {
    "apple-mail": {
      "command": "npx",
      "args": ["-y", "@mgcrea/mcp-apple-mail"]
    },
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "@mgcrea/mcp-apple-notes"]
    }
  }
}

パッケージはMITライセンスで、ライセンスキーは不要です。必要なのは権限だけであり、npm上では、それを起動するもの — エディタ、ターミナル — に付与します。それが、署名済み Cupertino.app が回避するトレードオフです。1つのフルディスクアクセス許可を、ホストごとに1つではなく、1つのバイナリが保持します。 docs/licensing.md を参照してください。

またはソースから実行:

git clone https://github.com/mgcrea/mcp-cupertino.git
cd mcp-cupertino
pnpm install
pnpm build

次に、ホストを絶対パスで packages/<surface>/dist/cli.js に向けます。

書き込みは、明示的に要求しない限りオフです — 設定 を参照してください。

メニューバーアプリ経由で実行する場合、ブリッジがすべてのサーバーをルーティングするため、フルディスクアクセスはCupertinoに付与され、エディタを起動したプロセスには付与されません:

make run      # build Cupertino.app, point it at packages/*/dist, launch it
make smoke    # handshake every server through the bridge

このリポジトリにチェックインされている .mcp.json は、そのパス向けに配線されています。make だけで、すべてのターゲットをリストします。

サーバー名が異なることに注意してください。上記のように手動で配線する場合、サーバーは apple-mail であり、そのホストプロセスが持つ権限で実行されます。Cupertino経由で配線する場合、それは cupertino-mail であり、アプリの権限で実行されます。2つの名前は2つのデプロイメントに対応しており、両方を持つことができます。アプリは自身の cupertino-* キーにのみ触れます — 他のサーバーに属する apple-mail エントリはそのまま残されます。

Cupertinoはマシン設定であり、プロジェクトの依存関係ではありません。したがって、ユーザーごとの設定に属します: Claude Desktop、Cursor、LM Studio、Windsurfではそれぞれ1つのファイル、CLIでは --scope user です。これがアプリのコピー可能なコマンドが使用するものです。意図的に --scope project ではありません。これは .mcp.json を書き込み、コミットされることを意味します — そのエントリは1台のMac上の1つのバンドルへの絶対パスであり、チームメイトには役に立たず、共有するのは無分別です。

どのクライアントが書き込まれ、どのクライアントがコマンドを取得するかは、人気の問題ではありません。アプリは、サーバーが mcpServers の下にある厳密なJSONの設定にのみマージされます。Visual Studio CodeはJSONC、CodexはTOMLであり、それらの再シリアライズは、手作業で管理されているファイル内のコメントを削除してしまいます。Claude Codeの ~/.claude.json は厳密なJSONですが、資格情報と実行中のセッションを保持しているため、メニューバーからの読み取り-変更-書き込みは、他の誰かの変更を落としてしまう可能性があります。これら3つは、貼り付けるための行を取得します。ChatGPTは完全に存在しません。リモートHTTPコネクタを受け入れるだけで、ローカルのstdioサーバーを生成することはできません。

このリポジトリ自身の .mcp.json は例外であり、サーバーを意図的に cupertino-*-dev と名付けています。これは apps/apple/.build を指しており、アプリの開発中は、開発ビルドとインストール済みビルドを並べて持つことを意味します。Claude Codeは2つのスコープで同じ名前のサーバーを報告し、競合として扱うため、サフィックスによって両方を使い続けることができます。

Cupertino.app には macOS 26以降 が必要です — そのアイコンはIcon Composerバンドルであり、それより古いものではレンダリングできません。サーバー自体はプレーンなNodeであり、そのような制約はありません。メニューバーアプリだけが対象です。

権限

2つの別々のmacOS権限があり、それらはサーバーを起動したプロセスに適用されます — エディタ、ターミナル、またはCupertinoのいずれか — 決してMail、Notes、Reminders自体には適用されません。

システム設定 → プライバシーとセキュリティ → フルディスクアクセス → 起動するアプリを追加し、再起動します。Mail.appに付与しても効果はありません。読み取りには権限が必要であり、Mailには付与されません。

フルディスクアクセスなしで動作するもの:

インデックスを必要とするツールは、インデックスがなくても消えません — ツールリストは allowWrites とそれ以外の何にも依存しない純粋な関数です。なぜなら、MCPクライアントはそれをキャッシュするからです。それらは、何が欠けているかを示す構造化された degraded 結果を返します。apple_mail_diagnostics / apple_notes_diagnostics は、どのレーンが稼働しているか、欠けているものを付与する方法を報告します。

ツール

読み取りツールは常に登録されます。書き込みツールは、書き込みが有効でない限り不可視です — 単に拒否されるのではありません。

Mail

Notes

Reminders

カレンダー

list_events は繰り返しイベントを展開するため、毎週の定例ミーティングは週ごとに1回返されます。すべての結果には展開がカバーすることがわかっている期間が含まれ、範囲がそれを超える場合は、結果が少なく返されるのではなく truncated が設定されます。イベントのリストが短いことは、午後が空いていることと区別がつかないからです。

連絡先

resolve_handles は電話番号とメールアドレスを名前に変換します。これによって Messages サーフェスが読めるようになります。名前が返ってくることを前提にせず、各結果の status を読んでください。unknown はよくあることでエラーではありません。また ambiguous は2つの連絡先が同じ番号を共有していることを意味し、推測ではなく名前を返さないことを示します。

削除ツールはありません。 連絡先のスクリプト辞書にはいかなる種類の削除コマンドもなく、ストアはポリシー上読み取り専用であるため、ここでのすべてのサーフェスで書き込みは Apple Events 経由で行われます。docs/contacts.md を参照してください。

メッセージ

書き込みツールは1つだけです。辞書に使えるコマンドが1つしかないからです。 sdef には send、login、logout がリストされていますが、他の2つはユーザーを所有するすべてのデバイスで iMessage からサインアウトさせてしまいます。公開できる編集、削除、既読マーク、リアクションの動詞はありません。

ここは Apple Events が書き込みレーンであり、それ以外の何ものでもない唯一のサーフェスです。ここでのすべての読み取りは失敗するため、APPLE_MESSAGES_ALLOW_WRITES がオフの場合、Apple Event は一切送信されず、Automation の許可も要求されません。

send_message は生のハンドルよりも list_chats の chatRef を優先します。Messages がスクリプトに対して参加者の列挙を拒否するため、既存の会話だけが確実にアドレス指定できる唯一のターゲットだからです。Apple Events は送信したものの識別子を返さないため、結果は chat.db と照合されます。reconciliation: "matched" は実際のメッセージ参照を保持し、"pending" は Messages が送信を受け入れたがまだ行を書き込んでいないことを意味します。Pending は失敗ではなく、再試行するとメッセージが2回送信されます。

全履歴の約3%のメッセージは、テキストが SQL では到達できないアーカイブ済みの NSArchiver ブロブにのみ保持されています。また Apple は2026年初頭にプレーン列の書き込みを停止したため、最近のものではほぼ100%が該当します。このサーバーはそれらをデコードします。すべての結果の textSource がどのレーンが応答したかを示します。docs/messages.md を参照してください。

Safari

読み取り専用であり、書き込み列は意図的に空です。 URL を開いたりリーディングリストに追加したりすることは、実際の表示中のブラウザを操作する Apple Event であり、このサーフェスで書き込みが試行されたことはありません。

list_tabs はバンドル全体でフルディスクアクセスなしで動作する唯一のツールです。代わりに Automation の許可が必要で、Safari が実行中である必要があります。タブの history フィールドが null であることは履歴に見つからないことを意味し、「訪問したことがない」ではありません。開いているタブの約55%だけが履歴行と一致します。リダイレクト、セッションパラメータ、履歴にコミットされなかったページはすべて、単に存在しない URL を生成するからです。

do JavaScript ツールはありません。 その動詞には「Apple Events から JavaScript を許可」が必要ですが、これは Safari の開発メニューのトグルであり、TCC の許可ではなく、その状態を確実に読み取ることもできません。それを提供することは、最も強力な機能が静かに失敗する健全なサーフェスを報告することを意味します。docs/safari.md を参照してください。

すべての名前には apple_mail_ / apple_notes_ / apple_reminders_ / apple_calendar_ / apple_contacts_ / apple_messages_ / apple_safari_ というプレフィックスが付きます。

設定

環境変数のみです。これらのサーバーは独自の秘密情報を保持しないため、設定ファイルはありません。プレフィックスは APPLE_MAIL_、APPLE_NOTES_、APPLE_REMINDERS_、APPLE_CALENDAR_、APPLE_CONTACTS_、APPLE_MESSAGES_、APPLE_SAFARI_ です。

allowWrites は変更をゲートしますが、Mail でのより大きな爆発半径はアーカイブ全体の読み取りです。それが *_ACCOUNTS の目的であり、正確に1箇所で強制されるため、どのクエリパスもそれを逃れることはできません。Mail はまた *_ROOT、*_ENVELOPE_INDEX、*_DEGRADED_MAX_MESSAGES、*_BODY_MAX_BYTES、*_BODY_SCAN_MAX、*_BODY_SCAN_BYTES、*_MAILBOX_CACHE_TTL_MS も受け取ります。packages/mail/src/config.ts を参照してください。

アプリ

メニューバーが Cupertino の全体のサーフェスです。Dock アイコンもメインウィンドウもありません。

アクティビティウィンドウはツールの名前のみを記録します。引数、メッセージ内容、結果は決して記録しません。これは「アシスタントが今、私のメールで何をしたのか」への答えであり、サーバーがエディタの内部ではなく、見えるアプリの下で実行される理由です。

書き込みはサーフェスごとにオンにするまでオフになっており、トグルは変更系ツールが登録されるかどうかを決定します。書き込みがオフのアシスタントは、それらが存在することすら見ることができません。

単一アプリである理由

フルディスクアクセスは分割できないディスク全体への単一の許可です。サーフェスごとに許可を与えても封じ込めにはならず、そのたびにシステム設定を開く手間がかかるため、すべてのサーフェスは Cupertino という1つの署名・公証済みアプリに同梱されています。docs/distribution.md には、Mac App Store がこれらを一切ホストできない理由も記録されており、その疑問が再び持ち上がることはありません。

しかし、許可だけがアプリが保持するものではなく、サーバーをエディタの下ではなくアプリの下で実行する唯一の理由でもありません。

docs/alternatives.md はそのリストの正直なバージョンです。他にどのようなものがアシスタント向けに Apple Mail を読み取るのか、そしてそれらのツールがどこで先行しているのかが書かれています。

ドキュメント

| docs/distribution.md | これがどのように配布されるか、そしてなぜApp Storeではないか | | docs/surfaces.md | どのサーフェスか、そしてそれぞれのコスト | | docs/licensing.md | 何がオープンで、何が販売され、何が信頼を買うか | | docs/alternatives.md | 他にApple Mailを読むもの、そしてどこで負けるか | | docs/mail-body.md | 本文検索レーン、そしてそれがどのように決定されるか | | docs/notes.md | Apple Notes フェーズ0の測定 | | docs/reminders.md | Apple Reminders フェーズ0の測定 | | docs/messages.md | Apple Messages: 測定、デコーダー、送信 | | docs/calendar.md | Apple Calendar フェーズ0の測定 | | docs/safari.md | Safari フェーズ0の測定 | | docs/envelope-index.md | Mailの観測されたEnvelope Indexスキーマ | | docs/verify.md | 実際のインデックスに対してMailサーバーをチェックする |

作業中

pnpm build          # every package
pnpm test           # every package
pnpm typecheck
pnpm lint
pnpm format

マーケティングサイトは独自のワークスペースであり、手動でデプロイされます:

pnpm --filter @mgcrea/cupertino-website dev     # astro dev
pnpm --filter @mgcrea/cupertino-website build   # static build

これは .idea/design/ のデザインキャンバスから構築され、ツール数はこのファイルではなく packages/*/src/tools/ から読み取ります — apps/website を参照してください。

Swift 側は xcodebuild で、Makefile によってラップされるのではなく名前が付けられています:

make app            # build Cupertino.app (Debug)
make run            # build, point at packages/*/dist, launch
make smoke          # handshake every server through the bridge
make stop           # quit and remove the socket

アプリのスクリーンショットは手作業ではなくキャプチャされます — apps/apple/Screenshots/ には設定とコミットされたゴールデンが保持され、ウェブサイトが出力をレンダリングします:

make screenshots          # capture, gate against the goldens, compose both sets
make screenshots-check     # gate only — fails if the UI drifted
make screenshots-update    # accept the captures as the new goldens (review the diffs first)
make screenshots-selftest  # prove the gate fails when it should

実行は各ショットの瞬間にポインターとアクティブなアプリを引き継ぐため、実行中はマシンを使用しないでください。ターミナル には画面収録の権限が必要ですが、Cupertino 自体には必要ありません。make screenshots-doctor はそれと、他に静かに失敗する2つのこと（キャプションフォントが解決するかどうか、出力サイズがストアが受け入れるものかどうか）をチェックします。

スクリーンショットが示すのは apps/apple/Cupertino/DemoSeed.swift のフィクスチャデータであり、この Mac ではありません: -ScreenshotMode ではアプリはホストを起動せず、独自のログとセッションをシードし、権限とストアの質問にテーブルから答えます。それがなければ、画像は1台のラップトップのTCC状態を報告し、そのホームディレクトリをマーケティングサイトに出力することになります。

フェーズ0のプローブはリポジトリ全体で読み取り専用です。測定するサーフェスの権限が必要で、出力をカウント、タイミング、DDLに編集します:

pnpm probe:mail      # Envelope Index — needs Full Disk Access
pnpm probe:mail-body # which lane can search message bodies — needs Full Disk Access
pnpm probe:notes     # Notes — the Apple Events half runs without it
pnpm probe:reminders # Reminders — the store path is a glob, so finding it is itself privileged
pnpm probe:messages  # chat.db — no Apple Events read lane exists, so this one needs the grant
                     #   --send-target=<handle> also checks the send lane's targeting, without sending
pnpm probe:calendar  # settles whether Calendar has a file lane at all
pnpm probe:safari    # History.db, and the Reading List hiding inside Bookmarks.plist
pnpm probe:contacts  # the resolver Messages needs — its own TCC grant, not Full Disk Access

プローブされたすべてのサーフェスには現在パッケージがあります。Safari は読み取り専用です — 変更を加えるツールは登録されておらず、それは省略ではなく記録された決定です: URLを開いたり、リーディングリストに追加したりすると、実際の表示可能なブラウザを操作することになり、プローブされたことはありません。docs/safari.md を参照してください。Messages は正確に1つの書き込みツール send_message を登録しており、それがスクリプティング辞書ができることのすべてです。 すべてのプローブは終了するのではなく劣化します — 実行されていないアプリや権限が付与されていない場合は発見として報告されます — また、--launch を渡さない限り、いずれもアプリを起動しません。それらの共有メカニズムは scripts/lib/probe-kit.mjs にあります。

リリースはパッケージごとにタグ付けされるため、タグは公開するものを示します: mail-v1.1.0、reminders-v1.1.0、calendar-v1.1.0、core-v1.1.0。アプリは app-v1.1.0 とタグ付けされ、独自のレーンでリリースされます — GitHubリリースに添付された署名・公証済みの Cupertino.zip と、そのSHA-256です。docs/distribution.md を参照してください。

リポジトリは mcp-cupertino です。npmパッケージは @mgcrea/mcp-apple-* のままです。なぜなら、それが人々がnpmで検索するものだからです。どちらの名前も重要ではありません。バンドル識別子 io.mgcrea.cupertino が実際に重要な文字列です。それを変更すると、すべてのユーザーのフルディスクアクセス許可が無効になるからです。

ライセンス

2つあります。なぜなら、2つの部分は同じものではないからです。

Cupertino はフルディスクアクセスを要求するため、ソースは読み取り可能なままです — それがそのような許可に対して負うものであり、読むことがポイントです。実行することは別の問題です: ライセンスチェックはソース内にあるため、どのビルドもキーを要求します（あなたのものか私たちのものか）。販売されるのは公証済みバイナリとその背後にあるメンテナンスです。サーバーはMITであり、キーなしで単独で動作します。その理由は docs/licensing.md にあります。