apple-productivity-mcp

Apple Productivity MCP

Codex、Claude Code、Claude Desktop、その他の stdio MCP クライアントから、Apple の生産性アプリ、書類、ファイル、メディアを操作するためのローカル macOS MCP サーバーです。

バージョン 3.0.0：17 グループにわたる 133 個のツールを備え、明示的に許可リストに登録したショートカットの任意実行にも対応します。Apple の自動化インターフェイスを介して Mac 上で動作します。ホスト型サービス、リスニングポート、サブスクリプション、Apple API キーは必要ありません。

ツールのリファレンス · 機械可読なスキーマ · 検証 · ソースのドキュメント · 変更履歴 · 公開 · ディレクトリのステータス

できること

アプリ／グループ	ツール数	対応範囲
Mail	12	アカウントとメールボックス、メッセージのメタデータ／本文、送信者／件名の検索、表示中の下書き、送信、既読／フラグの状態、移動／ゴミ箱への移動、メールボックスの作成、添付ファイル。
Calendar	12	カレンダーとイベント、イベントの作成／更新／削除、イベントのメモ、参加者、繰り返し、カレンダーの作成／名称変更／削除、表示アラームとイベント URL。
Reminders	15	アカウント／リスト、リマインダーとタイトル検索、メモ、優先度、期限、作成／更新／削除、リスト管理、完了／再開、フラグと通知日。
Notes	9	アカウント／フォルダ、メモの一覧表示／検索／読み取り、フォルダと HTML メモの作成、ロックされていないメモの更新と削除。
Contacts	9	検索と連絡先の詳細、グループとメンバー、連絡先／グループの作成、フィールドの更新、グループへの参加の追加／解除。
Pages	8	書類の一覧表示／オープン／作成、本文テキストの読み取り／置換／追記、保存、PDF／DOCX への書き出し、未保存の変更を保護したクローズ。
Numbers	11	書類、シート、表、表の作成、範囲を限定したセル範囲の読み取り／書き込み、保存、PDF／XLSX への書き出し、クローズ。
Keynote	9	書類とスライド、プレゼンテーションの作成、タイトル、本文、発表者ノートの追加／更新、保存、PDF／PPTX への書き出し、クローズ。
TextEdit	7	書類、テキストの作成／オープン／読み取り／置換／追記、RTF で保存、クローズ。
Safari	6	タブとページテキスト、URL チェックを行うタブのオープン／移動／クローズ、リーディングリスト。
Music	9	プレイリスト、トラック、検索、メタデータ、プレイリストの作成とトラックの追加、再生と音量。
Photos	9	アルバム／項目／検索、メタデータ、アルバムの作成、項目の追加、読み込み／書き出し、メタデータの更新。
Messages	3	アカウント／チャット、明示的に指定したアカウントを通じて、明示的に指定した宛先へテキストを送信。
Files	8	範囲を限定したフォルダ一覧表示、メタデータ／テキスト、テキストファイル／フォルダの作成、コピー、Spotlight によるファイル名検索、Finder のゴミ箱。
Finder	2	選択項目のメタデータ、許可されたパスの表示。
Shortcuts	2 + 1（オプトイン）	ショートカット／フォルダの一覧表示、設定済みの許可リストに登録された名前のショートカットのみ実行。
System	2	インストール済みアプリ／設定の検出、既知の Apple アプリの起動。

従来の 18 個のツール名は引き続きサポートされています。バージョン 3 ではデフォルトのカタログが拡張されています。以下から必要なアプリグループだけを選択してください。

対応範囲には限界があります。 Apple はスクリプトを通じて、すべてのアプリ機能を公開しているわけではありません。Messages の履歴、Contacts の削除、Pages のレイアウトテキストボックス、書類の完全なスタイル設定、Calendar の招待、Reminders のサブタスク／タグ／繰り返し、任意の Safari JavaScript、非公開の Apple データベースには対応していません。Home、Health、Wallet、Find My、Freeform の編集専用ツールもありません。ユーザーが作成し、許可リストに登録したショートカットを使えば、他のアプリで対応するアクションを実行できます。各ツールが受け付ける内容は、完全な入力スキーマに記載されています。

要件

• macOS および Node.js 20 以降。
• 操作する Apple アプリがインストールされ、設定されている必要があります。Pages、Numbers、Keynote はそれぞれ App Store から個別にインストールします。
• ローカルの stdio MCP サーバーに対応したクライアント。
• 起動するクライアント／プロセスが各アプリを操作するための macOS オートメーション権限。一部のファイルの場所では、「ファイルとフォルダ」へのアクセス権も必要です。

MCP クライアントが接続すると、サーバーが起動します。各オートメーション呼び出しでは、固定スクリプトと JSON 引数をタイムアウト付きで使用します。iCloud、Exchange、その他のアカウントの同期は、引き続きアプリ独自の設定に従います。

インストール

Codex

codex mcp add apple-productivity-local -- \
  npx -y @gambadio/apple-productivity-mcp@latest
codex mcp get apple-productivity-local

Claude Code

claude mcp add --transport stdio --scope user apple-productivity-local -- \
  npx -y @gambadio/apple-productivity-mcp@latest
claude mcp get apple-productivity-local

Claude Desktop およびその他の JSON 設定クライアント

クライアントの MCP 設定にこれを追加してから、再起動してください。

{
  "mcpServers": {
    "apple-productivity-local": {
      "command": "npx",
      "args": ["-y", "@gambadio/apple-productivity-mcp@latest"]
    }
  }
}

再現可能なインストールにするには、@latest を @3.0.0 に置き換えてください。テスト済みのローカル .mcpb バンドルとチェックサムを GitHub リリースで入手できます。自分でビルドする場合は、パッケージ化の手順を参照してください。このパッケージはユーザーの Mac 上で実行する必要があり、Linux コンテナやリモートホスティングサービスからユーザーのアプリにアクセスすることはできません。

設定

すべての設定は任意です。MCP クライアントのサーバー環境に設定し、新しい MCP プロセスを起動してください。

変数	デフォルト	動作
APPLE_MCP_ENABLED_GROUPS	すべてのグループ	上の表にあるグループ名を小文字でカンマ区切りに指定します。例：mail,calendar,reminders,notes。空の場合はすべてのグループが対象です。不明なグループがあると起動に失敗します。
APPLE_MCP_READ_ONLY	false	1 または true を指定すると、読み取り専用ツールのみが登録されます。0 または false を指定すると、選択したグループの書き込みツールも有効になります。
APPLE_MCP_FILE_ROOTS	[]	Files ツール、Finder での表示、Mail 添付ファイルの保存、Shortcut のファイル入力に使用する、存在する絶対パスのディレクトリを含む JSON 配列です。これらの操作を使用する場合に必須です。これらのルートの外に解決されるパスは拒否されます。
APPLE_MCP_SHORTCUTS	[]	実行を許可するショートカット名／識別子を含む JSON 配列です。リストが空の場合、apple_shortcuts_run は完全に省略されます。

Notes、リマインダー、ファイル、および許可する Shortcut を 1 つ指定する例：

{
  "mcpServers": {
    "apple-productivity-local": {
      "command": "npx",
      "args": ["-y", "@gambadio/[email protected]"],
      "env": {
        "APPLE_MCP_ENABLED_GROUPS": "system,notes,reminders,files,finder,shortcuts",
        "APPLE_MCP_FILE_ROOTS": "[\"/Users/YOUR_NAME/Documents\"]",
        "APPLE_MCP_SHORTCUTS": "[\"Prepare daily note\"]"
      }
    }
  }
}

YOUR_NAME とショートカット名を、Mac 上に存在する値に置き換えてください。iCloud Drive のディレクトリは、実際のローカル絶対パスを指定して含めることができます。

ファイルルートは上記の汎用ファイルツールを制限するものであり、Apple アプリのサンドボックスではありません。iWork／TextEdit の開く／保存／書き出しと、Photos の読み込み／書き出しでは、それらのアプリに付与された macOS 権限のもとで明示的なパスを使用します。Shortcuts は、許可されたショートカットに含まれる任意のアクションを実行でき、メッセージの送信や他の場所のデータの変更も可能です。許可リストに追加する前に、ショートカットの内容を確認してください。アプリグループのフィルタリングと読み取り専用モードは、公開されるツールの範囲を制御します。MCP のアノテーションはクライアント向けのヒントであり、認可システムではありません。

リクエスト例

• 「タイトルに『invoice』が含まれるリマインダーを探して、メモと期限を表示してください。」
• 「このアカウントに Notes フォルダを作成し、会議の要約を入れてください。」
• 「この Pages 書類を読み、隣に PDF を書き出してください。」
• 「Numbers のワークブックにあるシートと表を一覧表示してから、これらの値をセル B2:D6 に入力してください。」
• 「このタイトル、本文、発表者ノートを含む Keynote スライドを追加してください。」
• 「この送信者からの Mail メッセージを探し、選択した添付ファイルを許可済みの Documents フォルダに保存してください。」
• 「Photos のアルバムを一覧表示し、選択した項目を空のフォルダに書き出してください。」
• 「許可リストに登録した『Prepare daily note』ショートカットを実行してください。」

まずは検出ツールから使ってください。返された ID／名前を使用し、正確なフィールドを確認するにはツールのスキーマを調べてください。apple_system_capabilities はインストール済みアプリを特定しますが、事前にアクセスを許可するものでも、権限を証明するものでもありません。書き込みリクエストは実データを変更するため、対象と変更内容を明示してください。

データの取り扱いと保護措置

• サーバー側のアカウント、テレメトリーサービス、ネットワークリスナー、認証情報の保存はありません。
• 固定の JXA プログラムは、ユーザー値を実行可能なソースに補間せず、JSON 引数として受け取ります。任意のコードやシェルを実行するツールはありません。
• 新しいファイルコピーでは、既存ファイルの置き換えを拒否します。テキストの書き込みと書類の保存／書き出しでパスを置き換えるには、明示的な上書きオプションが必要です。写真の書き出し先には空のフォルダーが必要です。
• 汎用ファイル操作では、ルートの明示を必須とし、解決済みのパスを確認します。ファイルの削除は Finder のゴミ箱を経由します。ゴミ箱を空にするツールはありません。
• コレクションの読み取りとテキスト／セル範囲には上限があります。ロックされたメモは読み取りも変更も行いません。Safari のタブを変更する際は、想定 URL と照合してインデックスのずれを防ぎます。
• 読み取り専用モードでは変更操作が非表示になります。各ツールは、読み取り専用、破壊的、冪等、オープンワールドの各注釈を宣言します。
• メール、メッセージ、書類の変更、リマインダー、連絡先、メディアの編集は、同期されたり、他の人に届いたりする場合があります。送信結果が示すのはアプリへの送信であり、配信が独立して確認されたことを意味しません。
• タイムアウトや複数ステップのエラーにより、変更が一部だけ適用される場合があります。書き込みを再試行する前に対象を確認してください。
• MCP クライアントに返されたデータは、そのクライアントのアクティブなモデルセッションの一部となり、そのデータ管理設定に従います。ローカルで実行しても、コンテンツがモデルセッションの外にとどまるとは限りません。十分な OS 権限を持つローカルプロセスからは、JSON 入力を確認できます。

開発と検証

npm ci
npm test
npm run docs:tools
npm audit --omit=dev
npm pack --dry-run

テストでは、アプリのフィクスチャに対して静的な自動化プログラムを実行し、一時フォルダー内でファイルシステムの境界を検証したうえで、実際の stdio MCP サーバーを初期化します。メッセージの送信や個人用アプリデータの編集は行いません。

既存の読み取り専用 Mail／Calendar／Reminders 統合テストスイートを実行するには、Automation の権限を付与した後、次を実行します。

npm run test:integration

実環境での検証はアプリごとに異なります。 リリース開発用 Mac には Pages、Numbers、Keynote がインストールされていなかったため、これらのツールはフィクスチャによるテストを実施していますが、実際の iWork での検証は行っていません。検証結果と制限事項および実装ソースを参照してください。ツール数は、すべての操作がすべてのアプリ／macOS バージョンで検証済みであることを示すものではありません。

トラブルシューティング

Automation を利用できない／許可されていない／タイムアウトする： 「システム設定」→「プライバシーとセキュリティ」→「オートメーション」を開き、起動クライアントによる該当する Apple アプリの操作を許可してください。タイムアウトは、アプリの処理中や iCloud データの読み込みが遅い場合にも発生することがあります。書き込みをむやみに再試行しないでください。権限や設定を変更した後は、クライアントを再起動してください。

アプリが見つからない： アプリをインストールして一度起動し、apple_system_capabilities を確認してください。OS のプロセスサンドボックスによって LaunchServices が制限される場合もあります。適切な macOS アクセス権を持つローカルクライアントを実行してください。

ファイルルートが必要／許可されたルート外のパス： APPLE_MCP_FILE_ROOTS に、既存の絶対ディレクトリを含む JSON 配列を設定してください。シンボリックリンクを使って許可リストの外へ移動することはできません。不足している親フォルダーは先に作成してください。

オブジェクトが見つからない／名前があいまい： アプリの現在のアカウント、リスト、書類、またはオブジェクト ID を再取得してください。名前は言語やプロバイダーによって異なります。名前で編集する前に、重複する書類を閉じるか、名前を変更してください。

Contacts に未保存の変更がある： 変更操作を使う前に、Contacts で保留中の編集を保存するか破棄してください。Contacts のスクリプトによる保存では、保留中の変更がすべて保存されるためです。

ツールが見つからない： アプリグループ／読み取り専用の設定を確認し、新しいセッションを開始してから、クライアントで mcp get／mcp list を確認してください。ショートカットの実行ツールは、許可リストが空でない場合にのみ表示されます。ツールを表示するためにアプリをインストールする必要はありません。

spawn ... ENOENT： Node と npx がデスクトップクライアントの PATH から参照できることを確認してください。必要に応じて、command -v npx が返すフルパスを使用してください。

更新または削除

新しい MCP プロセスの起動時に@latestが解決されます。リリースを公開した後は、クライアントを再起動してください。既存のプロセスは、読み込み済みのバージョンで引き続き動作します。v3 で元のアプリの対象範囲を維持するには、APPLE_MCP_ENABLED_GROUPS=mail,calendar,remindersを設定してください。

codex mcp remove apple-productivity-local
claude mcp remove apple-productivity-local --scope user

登録を削除しても、Apple のデータは削除されず、npm のキャッシュもクリアされません。

配布

正式なソース：GitHub。パッケージ：npm。レジストリ上の識別子：io.github.gambadio/apple-productivity-mcp。

ディレクトリの状況では、公開中の掲載情報、審査待ちの申請、ログイン要件、互換性がない、または一時停止中の配布先を区別しています。サードパーティの掲載内容は、最新のリリースに追いついていない場合があります。掲載および推奨の判断は、それぞれの管理者が行います。

ライセンス

MIT。Apple とは無関係の独立したプロジェクトであり、Apple との提携や Apple による承認を受けていません。