macos-mcp

macOS 上の Reminders、Calendar、Notes、Mail、Messages、Contacts を AI エージェントまたはシェルから操作します。

Apple はこれらのアプリに対して3つの自動化サーフェスを提供していますが、それぞれどこかで失敗します。EventKit は Notes、Mail、Messages、Contacts に到達できません。JXA による Messages の読み取りは Sonoma 以降では何も返しません。JXA による Mail の読み取りは実際の受信トレイに対して60秒でタイムアウトします。このプロジェクトはアプリごとに機能するブリッジを使用し、その理由を DECISION.md に文書化しています。

Mac が必要です。 これらのブリッジは EventKit、Apple Events、およびローカルの Apple データベースの SQLite 読み取りです。Linux、Windows、iOS、Android、ブラウザビルドはありません。

3つの使用方法

MCP サーバーとして。 ローカル stdio トランスポートで、同じ Mac 上の任意の MCP 対応クライアント（Claude Code、Claude Desktop、Cursor、Zed、Continue、ChatGPT デスクトップ）で動作します。8つのツールがあり、ツール に一覧があります。

エージェントスキルとして。 同じブリッジをシェルコマンドとして呼び出し、ツールスキーマをコンテキストに読み込みません。MCP サーバーはセッション開始時に8つのツール定義をモデルの前に置きますが、セッションが Mac アプリに触れるかどうかは関係ありません。スキルは何かがトリガーされるまで1行の説明です。スキルは skills/macos/ に、選択方法は docs/mcp-vs-skill.md にあります。

CLI として。 EventKitCLI はスタンドアロンの Swift バイナリで、stdout に JSON を出力します。スキル内の JXA および SQLite レシピは、シェルが存在する場所ならどこでも実行できます。

Related MCP server: Apple MCP

クイックスタート

Claude Code プラグインとしてインストール

/plugin marketplace add krmj22/macos-mcp
/plugin install macos-mcp@krmj22-plugins

これらを Claude Code 内で実行します。プラグインは npx -y mcp-macos を介して MCP サーバーを配線するため、別途インストール手順は不要です。

npm からインストール

npm install -g mcp-macos
# or use npx via your client's MCP config (no global install needed)

または MCPB（Claude Desktop）でインストール

最新の GitHub リリース から .mcpb バンドルをダウンロードし、Claude Desktop にドラッグします。バンドルには事前ビルドされたユニバーサル Swift バイナリ（arm64 + x86_64）が含まれているため、Xcode Command Line Tools は不要です。

またはソースからビルド

git clone https://github.com/krmj22/macos-mcp.git
cd macos-mcp
pnpm install
pnpm build

セットアップの確認

macos-mcp --check   # or: node dist/index.js --check

macOS バージョン、Node.js、EventKit バイナリ、フルディスクアクセス、JXA 自動化権限をチェックします。

サーバーの代わりにスキルとして使用

スキルをエージェントのスキルディレクトリにコピーします。MCP サーバーもツールスキーマもコンテキストにありません。

git clone https://github.com/krmj22/macos-mcp.git
cp -R macos-mcp/skills/macos ~/.claude/skills/macos

スキルは EventKitCLI、osascript、sqlite3 を直接呼び出すため、Swift バイナリが PATH にある必要があります：

cd "$(mktemp -d)" && npm i mcp-macos --no-save \
  && mkdir -p ~/.local/lib/mcp-macos/bin \
  && cp node_modules/mcp-macos/bin/EventKitCLI ~/.local/lib/mcp-macos/bin/EventKitCLI \
  && ln -sf ~/.local/lib/mcp-macos/bin/EventKitCLI ~/.local/bin/EventKitCLI

どちらの方法でも同じ権限が適用されます。権限 を参照してください。

ツール

アンダースコア（reminders_tasks）とドット（reminders.tasks）の両方の表記が機能します。

設計ノート

• 読み取りは SQLite、書き込みは JXA。 JXA による Mail の読み取りはスケールせず、実際の受信トレイでは60秒のタイムアウトが発生します。また、JXA による Messages の読み取りは macOS Sonoma 以降では完全に壊れています。このプロジェクトは chat.db と Mail の Envelope Index を直接読み取ります。Gmail の labels 結合テーブルも [Gmail]/All Mail アカウント用に含まれます。書き込みは引き続き JXA を介して行われます。Apple Events がそれらをトリガーする唯一の API だからです。ADR-001 を参照してください。

• アプリごとのハイブリッドバックエンド。 各アプリは機能するブリッジを使用します：Reminders と Calendar には EventKit を介した Swift CLI、Notes、Contacts、Mail の書き込み、Messages の送信には JXA、Mail と Messages の読み取りには SQLite。アーキテクチャ図 にファンアウトが示されています。

• ツール間の連絡先エンリッチメント。 共有レイヤーが生の電話番号とメールアドレスを Messages、Mail、Calendar 全体の連絡先名に解決します。SQLite の AddressBook ストアを介したバルクキャッシュは、1,100エントリで50ms未満。ターゲット検索は JXA の whose() を介して行います。ADR-002 を参照してください。

• 事前チェック。 macos-mcp --check は、実行前に macOS バージョン、Node.js、EventKit バイナリ、フルディスクアクセス、JXA 権限を検証し、失敗した項目については関連するシステム設定ペインへのディープリンクを提供します。

セットアップ

前提条件

• Node.js 20+

• macOS

• Xcode Command Line Tools（Swift コンパイル）

クライアント設定

JSON 設定はすべてのクライアントで同じです。場所だけが異なります。

{
  "mcpServers": {
    "macos-mcp": {
      "command": "npx",
      "args": ["mcp-macos"]
    }
  }
}

権限

macOS は初回使用時にアクセスを要求します。プロンプトが表示されたら 許可 をクリックします。

Messages と Mail は SQLite データベースを直接読み取るため、ターミナルアプリ（Terminal、iTerm2 など）には フルディスクアクセス が必要です。

macos-mcp --check を実行して確認します。失敗した場合は トラブルシューティング を参照してください。

トラブルシューティング

クイックフィックスコマンド

# Open specific settings panes
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Reminders"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Calendars"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Automation"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"

フルディスクアクセス（Messages と Mail）

Messages と Mail は SQLite データベース（~/Library/Messages/chat.db と ~/Library/Mail/V10/MailData/Envelope Index）を読み取ります。これらにはターミナルアプリのフルディスクアクセスが必要です。

# Find your real node binary (version managers use shims)
node -e "console.log(process.execPath)"

# Reveal it in Finder for drag-and-drop into FDA settings
open -R "$(node -e "console.log(process.execPath)")"

# Open Full Disk Access settings
open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"

バージョンマネージャーユーザー（Volta、nvm、fnm）：node コマンドはシムです。システム設定には実際のバイナリが必要です：

システム設定は隠しディレクトリ内のバイナリを表示しない場合があります。上記の open -R を使用して Finder で表示し、FDA リストにドラッグします。

JXA 自動化（Notes、Mail、Contacts）

初回使用時に macOS が自動化アクセスを要求します。システム設定 > プライバシーとセキュリティ > 自動化 から許可します。

権限を確認：

osascript -l JavaScript -e 'Application("Contacts").people().length'
osascript -l JavaScript -e 'Application("Calendar").calendars().length'
osascript -l JavaScript -e 'Application("Reminders").defaultList().name()'
osascript -l JavaScript -e 'Application("Mail").inbox().messages().length'
osascript -l JavaScript -e 'Application("Notes").notes().length'

各コマンドは値を返すはずです。ハングする場合は、権限ダイアログが表示されようとして（失敗して）いることを意味します。

Gmail ラベル / 受信トレイのメッセージが欠落

Gmail はすべてのメッセージを [Gmail]/All Mail に保存し、ラベルを使用してフォルダのメンバーシップを管理します。サーバーは直接のメールボックスとラベル結合テーブルの両方をチェックします。Gmail の受信トレイメッセージが欠落している場合は、Mail アプリが完全に同期されていることを確認してください。

開発

pnpm install          # Install dependencies
pnpm build            # Build TypeScript + Swift binary
pnpm test             # Run full test suite
pnpm lint             # Lint and format (Biome + TypeScript)
pnpm dev              # Run from source via tsx

本番エントリポイント（bin/run.cjs）には pnpm build が必要です。ローカル開発には pnpm dev を使用します。

アーキテクチャ

flowchart LR
    Client[MCP Client<br/>Claude Code, Cursor, Desktop] -->|stdio| Server[macos-mcp]

    Server --> Swift[Swift CLI]
    Server --> JXA[JXA]
    Server --> SQLite[SQLite Readers]

    Swift -->|EventKit| Reminders[Reminders]
    Swift -->|EventKit| Calendar[Calendar]

    JXA -->|Apple Events| Notes[Notes]
    JXA -->|Apple Events| Contacts[Contacts]
    JXA -->|writes only| Mail[Mail]
    JXA -->|send only| Messages[Messages]

    SQLite -->|Envelope Index| Mail
    SQLite -->|chat.db| Messages
    SQLite -->|AddressBook| Enrich[Contact<br/>Enrichment Cache]

Apple アプリへの3つのブリッジ：

• EventKit（Swift バイナリ）。 Reminders、Calendar。コンパイルされた Swift CLI で、JSON を返します。

• JXA。 Notes、Mail の書き込み、Contacts。osascript -l JavaScript で実行されるスクリプト。

• SQLite。 Messages の読み取り（~/Library/Messages/chat.db）、Mail の読み取り（~/Library/Mail/V10/MailData/Envelope Index）。JXA によるメッセージ読み取りは Sonoma 以降で壊れています。JXA によるメール読み取りは実際の受信トレイには遅すぎます。

Mail と Messages はハイブリッドパスを使用します：書き込みには JXA（送信/下書きをトリガーする唯一の方法）、読み取りには SQLite（スケールする唯一の方法）。アーキテクチャ決定記録については DECISION.md を参照してください。

依存関係

ランタイム： @modelcontextprotocol/sdk、zod

開発： typescript、tsx、jest、@biomejs/biome

クレジット

MCP サーバーレイヤーは FradSer/mcp-server-apple-events（MIT）から始まりました。EventKit Swift CLI、SQLite 読み取りパス、連絡先エンリッチメント、事前チェック、スキルサーフェスはここで追加されました。

ライセンス

MIT

貢献

CONTRIBUTING.md を参照してください。