Apple Calendar MCP

Apple Calendar MCP は、macOS 上の Apple Calendar に AI アシスタントを安全に接続するためのローカルファーストの Model Context Protocol サーバーです。

TypeScript 製の MCP サーバー、Swift 製の EventKit ヘルパー、SQLite によるローカル状態管理、そしてネイティブな macOS セットアップアプリで構成されています。カレンダーデータは Mac 上に留まり、ユーザーがどのカレンダーを表示するかを選択でき、書き込みは権限モード、確認ゲート、重複チェック、冪等性、ロールバック記録、監査ログ、変更フィードによって保護されています。

主な機能

• MCP ツールを通じて Apple Calendar のカレンダー、イベント、空き状況、権限を読み取ります。

• イベントの作成、更新、再スケジュール、削除を、デフォルトでプレビュー確認による安全性を備えて行います。

• サーバー側でカレンダーの許可リストを強制し、ブロックされたカレンダーがエージェントから見えないようにします。

• ロールバック記録、監査記録、コンパクトなスナップショット、トークン効率の良い変更フィードを追跡します。

• Claude Desktop、Codex、Cursor、OpenClaw、および汎用 MCP クライアント向けのクライアント設定を生成します。

• カレンダー権限、許可リスト、権限モード、設定生成、検証のためのネイティブな macOS セットアップウィザードを提供します。

Related MCP server: nucleus-apple-mcp

アーキテクチャ

flowchart TD
  A["MCP Client<br/>Claude, Codex, Cursor, OpenClaw"] --> B["TypeScript MCP Server"]
  B --> C["Calendar Service Layer"]
  C --> D["Swift EventKit Helper"]
  D --> E["Apple Calendar / EventKit"]
  C --> F["SQLite Local State"]
  F --> G["Config, Audit, Rollback,<br/>Snapshots, Change Feed,<br/>Idempotency"]
  H["Native macOS Setup App"] --> D
  H --> F

MCP サーバーは stdio 経由で通信します。ログは stderr またはオプションのローカルログファイルに書き込まれ、stdout には決して書き込まれないため、MCP プロトコルのトラフィックはクリーンな状態に保たれます。

要件

• Apple Calendar と EventKit にアクセスできる macOS。

• Node.js >=22.5。

• Xcode Command Line Tools または Xcode による Swift ツールチェーン。

• Claude Desktop、Codex、Cursor、OpenClaw、またはその他の stdio 互換クライアントなどの MCP クライアント。

ソースからのインストール

git clone <repo-url>
cd apple-calendar-mcp
npm install
npm run build
npm run helper:bundle
npm run helper:setup

セットアップアプリでは、次の手順を進めます。

1. カレンダー権限の説明とリクエスト。

2. カレンダー許可リストの選択。

3. 権限モードの選択。

4. MCP クライアント設定の生成。

5. 検証チェックとテスト接続。

生成されたローカル設定は次の場所に保存されます。

~/Library/Application Support/AppleCalendarMCP/

MCP クライアントのセットアップ

検証済みのクライアント設定を生成します。

npm run client-configs:generate

生成されたファイルを .generated/client-configs/ からクライアントにコピーまたはマージします。

• Claude Desktop: claude_desktop_config.json

• Codex: codex.config.toml を ~/.codex/config.toml に追記

• Cursor: cursor.mcp.json を ~/.cursor/mcp.json またはプロジェクトの .cursor/mcp.json にコピーまたはマージ

• OpenClaw: openclaw.openclaw.json を ~/.openclaw/openclaw.json にマージ

• 汎用 MCP クライアント: generic-mcp-client.json を使用

コピー後に検証します。

npm run client-configs:validate
npm run client-configs:diagnose

生成された設定は、絶対パスの Node 実行ファイル、絶対パスの MCP サーバーエントリポイント、および env ブロックを使用します。コマンドと引数がシェル文字列に結合されることはないため、パスにスペースが含まれる場合の失敗を回避できます。

npx 起動パス

公開可能なサーバーパッケージは、このバイナリを公開します。

npx apple-calendar-mcp

ローカル開発およびリリース候補では、次を推奨します。

npm run start:mcp

npm に公開する前に、内部ワークスペースパッケージを依存順に公開するか、npm run release:package によって生成されたリリース成果物を使用してください。

セキュリティモデル

Apple Calendar MCP は多層防御を中心に設計されています。

• macOS のカレンダー権限が EventKit アクセスの前に必要です。

• カレンダー許可リストにより、エージェントが表示できるカレンダーが制限されます。

• 読み取り専用、書き込み前確認、信頼済み書き込み、フル書き込みの各モードが書き込みリスクを制御します。

• MVP の書き込みには、明示的な確認またはプレビュー確認フローが必要です。

• 破壊的操作や曖昧な操作は推測せずに意味的エラーを返します。

• 繰り返しイベントの書き込みには明示的なスコープが必要です。

• カレンダーコンテンツは信頼できない入力として扱われます。

• 監査記録、ロールバック記録、冪等性キー、変更フィードはローカルに書き込まれます。

完全なセキュリティモデルについては、docs/Security Specification.md を参照してください。

スクリーンショット

リリース用スクリーンショットのプレースホルダー:

• セットアップウィザードのようこそ画面とカレンダー権限ステップ。

• カレンダー許可リストと権限モードのステップ。

• クライアント設定と検証のステップ。

• 設定と診断画面。

公開配布前に、署名済みリリースのスクリーンショットを撮影してください。

トラブルシューティング

• カレンダーアクセスが拒否された場合: システム設定 > プライバシーとセキュリティ > カレンダー を開き、ヘルパーアプリを有効にします。

• セットアップで MCP サーバーの起動が赤い場合: npm run build を実行し、packages/mcp-server/dist/index.js が存在することを確認します。

• Cursor または Codex が接続できない場合: npm run client-configs:generate で設定を再生成し、コピーした設定が絶対パスを使用していることを確認します。

• クライアントがサーバーを認識するがツールが表示されない場合: 設定変更後に MCP クライアントを再起動し、npm run client-configs:diagnose を実行します。

• stdout/stderr の分離に失敗する場合: MCP サーバーパスから stdout ログを削除します。ログは stderr に送る必要があります。

• 大規模な読み取りが失敗する場合: より狭い日付範囲を使用してください。読み取りサービスは内部で大きなウィンドウをチャンク分割しますが、非常に大きな EventKit リクエストでは再試行が必要になる場合があります。

開発

npm install
npm run build
npm test
npm run helper:bundle
npm run helper:setup

便利なコマンド:

• npm run typecheck

• npm run client-configs:generate

• npm run client-configs:validate

• npm run release:verify

• npm run release:package

セキュリティに影響する変更を行う前に、docs/Development Guide.md をお読みください。

リポジトリ構造

apps/macos-helper/        Swift EventKit bridge and native setup app
packages/mcp-server/      MCP stdio server and tool registration
packages/calendar-service/Business logic for reads, writes, rollback, snapshots
packages/sqlite-store/    Local SQLite persistence and migrations
packages/shared/          Shared schemas and typed contracts
scripts/                  Helper, config, diagnostics, and release scripts
tests/                    Phase-based safety and behavior tests
docs/                     Consolidated maintainer and release documentation

リリース

再現可能なローカルリリース成果物を作成します。

npm run release:package

成果物とチェックサムは次の場所に書き込まれます。

dist/release/

GitHub リリースワークフローは、v* に一致するタグプッシュ時に同じパッケージスクリプトを実行します。

ロードマップ

• 署名・公証済みの macOS リリースパッケージ。

• パッケージ名前空間の確認後の公開 npm 公開ワークフロー。

• サポート対象の MCP クライアント全体での、より多くのエンドツーエンドのクライアントスモークテスト。

• スナップショット/変更フィードのページネーションベンチマークの拡張。

• アプリ内スクリーンショットキャプチャと公開ドキュメントアセットの改善。

貢献

セキュリティ、信頼性、ユーザーの信頼、MCP コンプライアンス、保守性が利便性に優先します。変更はスコープを絞り、完全なテストスイートを実行し、動作が変わった場合はドキュメントを更新してください。権限チェック、許可リスト、確認ゲート、ロールバック記録、監査記録、冪等性チェック、または意味的エラーを迂回しないでください。

まずは以下から始めてください。

• docs/Product Specification.md

• docs/Technical Specification.md

• docs/Security Specification.md

• docs/Development Guide.md

• docs/Installation Guide.md

• docs/Release Checklist.md