mac-control-mcp

mac-control-mcp

macOS を完全に自動化するネイティブの Swift 製 MCP サーバーです。署名済みの .app バンドルに 153 個のツールを収録しています。Python、Node ランタイム、Electron は不要です。パラメーターを含む全ツール一覧：docs/TOOLS.md。

MCP 対応クライアント（Claude Desktop、Claude Code、Cursor など）に、次の操作を可能にします。

• 実行中のあらゆるアプリのアクセシビリティツリーの読み取りと変更
• Safari と Chrome の操作（タブ、ナビゲーション、JS の評価）
• 画面、ディスプレイ、または特定のウィンドウのキャプチャ（ScreenCaptureKit）
• 画面上の内容の OCR
• クリック、入力、スクロール、ドラッグ、キーイベントの送信
• ウィンドウの操作（移動／サイズ変更／フルスクリーン／最小化／メイン化）
• クリップボードの管理
• アプリの起動／アクティブ化／終了
• Spotlight のインデックス（NSMetadataQuery）の検索と結果の起動
• ダークモードと音量の切り替え、ディスプレイの一覧表示、メニューの確認

インストール

macOS 14.0 以降が必要です。簡単な順に 4 つの方法があります。

1. ワンクリックインストール（Claude Desktop、推奨）

サーバーは MCP Bundle として公開されています。これは Claude Desktop が直接読み込む manifest.json を含む zip です。

1. 最新リリースから mac-control-mcp-v<version>.mcpb をダウンロードします。
2. .mcpb ファイルをダブルクリックします。Claude Desktop にインストールダイアログが表示されます。
3. 「インストール」をクリックします。サーバーは mac-control-mcp という名前で登録され、新しいチャットですぐに利用できます。
4. 最初のツール呼び出し時に、macOS の TCC 同意プロンプト（画面収録、アクセシビリティ、Apple Events）が表示されます。3 つすべてを一度許可してください。バンドルは Developer-ID で署名され、公証済みのため、許可はアップデート後も保持されます。

公式 MCP Registry にも io.github.AdelElo13/mac-control-mcp として掲載されています。そのため、レジストリに対応する MCP クライアントなら、「mac-control」を検索して見つけることができます。

2. npm / npx 経由でインストール

ファイルパスではなく、コマンドラインで設定するクライアント向けです。npm パッケージ mac-control-mcp は薄いランチャーです。実行時依存関係はなく、インストール時に、このリポジトリの GitHub リリースから該当バージョンの公証済み MacControlMCP.app をダウンロードし、公開されている .sha256 と照合して検証します。また、インストールディレクトリの外に展開されるアーカイブ内のエントリーを拒否し、codesign --verify --deep --strict、spctl --assess --type execute、および固定された Team ID（A3W973JZ49）を使ってバンドルを再検証します。そのため、初回実行時は約 3 MB をダウンロードします。2 回目以降はローカルで実行されます。

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "mac-control-mcp": {
      "command": "npx",
      "args": ["-y", "mac-control-mcp"]
    }
  }
}

Claude Code：

claude mcp add mac-control-mcp -- npx -y mac-control-mcp

Cursor — ~/.cursor/mcp.json：

{
  "mcpServers": {
    "mac-control-mcp": {
      "command": "npx",
      "args": ["-y", "mac-control-mcp"]
    }
  }
}

ChatGPT（開発者モード、ローカル MCP コネクター）— mcp.json：

{
  "mcpServers": {
    "mac-control-mcp": {
      "command": "npx",
      "args": ["-y", "mac-control-mcp"],
      "transport": "stdio"
    }
  }
}

2 つのフラグはバイナリに転送せず、ランチャー自体が処理します。

npx -y mac-control-mcp --version    # version of the bundled .app
npx -y mac-control-mcp --app-path   # path to MacControlMCP.app

macOS の権限を手動で付与する場合は、--app-path が必要です。TCC の許可は、npx やスクリプトではなく、このプロセスを起動する MCP ホストアプリケーション（Claude Desktop、Cursor、ターミナル）に付与されます。クライアントから permissions_status ツールを一度実行すると、不足している許可と、その許可がどのアプリに属するかを確認できます。

MAC_CONTROL_MCP_SKIP_DOWNLOAD=1 を設定するとダウンロードをスキップします（CI、サンドボックス化されたビルド向け）。HTTPS_PROXY と NO_PROXY にも対応しています。

3. ビルド済みアプリをダウンロードする

Claude Desktop を使用しない場合や、手動で管理したい場合：

1. 最新リリースから MacControlMCP-v<version>-macos-universal.tar.gz をダウンロードします。
2. 展開し、MacControlMCP.app を ~/Applications/ に移動します。
3. MCP クライアントで、次のバイナリを指定します。

{
  "mcpServers": {
    "mac-control-mcp": {
      "type": "stdio",
      "command": "/Users/you/Applications/MacControlMCP.app/Contents/MacOS/MacControlMCP"
    }
  }
}

このブロックを ~/Library/Application Support/Claude/claude_desktop_config.json（Claude Desktop）または ~/.claude.json → mcpServers（Claude Code）に追加します。

公開されている SHA-256 と照合してダウンロードを検証します。

shasum -a 256 MacControlMCP-v<version>-macos-universal.tar.gz
# should match MacControlMCP-v<version>-macos-universal.sha256 on the release

4. ソースからビルドする

コントリビューター向け、またはコードを調整したい場合に使用します。Swift 6 / Xcode 16+ が必要です。

git clone https://github.com/AdelElo13/mac-control-mcp.git
cd mac-control-mcp
./scripts/build-bundle.sh

~/Applications/MacControlMCP.app/Contents/MacOS/MacControlMCP が生成されます。キーチェーンに Developer ID 証明書がない場合は、アドホック署名にフォールバックします（ローカルでの使用には対応していますが、TCC の許可はビルドのたびにリセットされます）。

既存の Apple Developer アカウントを使って、再署名と再公証を行うには：

# one-time: store notary credentials in keychain
xcrun notarytool store-credentials "mac-control-mcp" \
    --apple-id "[email protected]" --team-id "XXXXXXXXXX"

# subsequent builds:
NOTARIZE_PROFILE=mac-control-mcp ./scripts/build-bundle.sh

ツール一覧

選択されたカテゴリです。この表は厳選された一部であり、すべての一覧ではありません。 各ツールの説明と必須／任意のパラメーターを含む、完全な自動生成ツールリファレンス（ツールレジストリから直接再生成されるため、内容が古くなりません）については、docs/TOOLS.md を参照してください。

カテゴリ	ツール
権限	permissions_status, request_permissions
アクセシビリティ	find_element(s), query_elements, list_elements, get_ui_tree, ax_tree_augmented, get_element_attributes, set_element_attribute, read_value, perform_element_action, wait_for_element, scroll_to_element
アプリのライフサイクル	list_apps, launch_app, activate_app, quit_app, force_quit_app, wait_for_app, focused_app
ウィンドウ	list_windows, focus_window, move_window, resize_window, set_window_state, wait_for_window, move_window_to_display
入力	click, mouse_event, drag_and_drop, scroll, type_text, press_key, press_key_sequence, key_down, key_up, convert_coordinates
メニュー	click_menu_path, list_menu_paths, list_menu_titles
ブラウザー	browser_list_tabs, browser_get_active_tab, browser_navigate, browser_new_tab, browser_close_tab, browser_eval_js, browser_dom_tree, browser_visible_text, browser_iframes
画面	capture_screen, capture_screen_v2, capture_window, capture_display, ocr_screen
クリップボード	clipboard_read, clipboard_write, clipboard_clear
Spotlight	spotlight_search, spotlight_open_result
システム	set_volume, set_dark_mode, list_displays
ファイルダイアログ	file_dialog_set_path, file_dialog_select_item, file_dialog_confirm, file_dialog_cancel, wait_for_file_dialog
Apple アプリ	mail_send, imessage_send, imessage_list_recent, calendar_create_event, calendar_list_events, reminders_create, reminders_list, contacts_search
音声と録音	speech_to_text, text_to_speech, audio_record, record_screen
元に戻す	undo_last_action, undo_peek

ツールは合計153個です。生成された完全な一覧については、docs/TOOLS.md を参照してください。

ツールの使い分け

目的が重複するツールがいくつかあります。実際の実装に基づく使い分けは次のとおりです。

画面キャプチャ — capture_screen vs capture_screen_v2 vs capture_window vs capture_display

• capture_screen — メインディスプレイ（またはその中の矩形領域）を PNG ファイルに保存し、ファイルパスと幅・高さを返します。シンプルで同期的に動作し、サイズ制限は適用されません。
• capture_screen_v2 — メインディスプレイのみを対象としますが、PNG を ~/.mac-control-mcp/artifacts/<sha256>.png の下にコンテンツアドレス指定のアーティファクトとして保存し、{content_ref, bytes, sha256} を返します。デフォルトでは inline=false に設定され、max_dimension／max_bytes（デフォルトは 4000px／4MB）に合わせて縮小されます。これは特に、大きなインライン画像で MCP クライアントのコンテキストウィンドウを圧迫しないようにするためです（説明には claude-code の問題 #13383／#45785 に対する修正と記載されています）。画像をそのままディスクに保存するのではなく、LLM のコンテキストに渡す場合はこちらを優先してください。
• capture_window — ディスプレイ全体ではなく、PID で指定した特定のウィンドウのスクリーンショットを撮影します（必要に応じて title_contains で絞り込めます）。
• capture_display — マルチモニター環境で、list_displays によるインデックスを指定して特定の物理ディスプレイのスクリーンショットを撮影します。

アクセシビリティツリー／要素の検索 — find_element vs find_elements vs query_elements vs list_elements vs get_ui_tree vs ax_tree_augmented

• list_elements — PID に対応する操作可能な要素を一覧表示します（「クリックできるもの」の実用的なフラット表示です）。
• find_element — PID に対応する要素のうち、ロール／タイトルのフィルターに一致する最初の要素を返します。
• find_elements — find_element と同じ条件で検索しますが、最初の要素だけでなく、一致するすべての要素を返します。
• query_elements — ロール／タイトル／値を対象に正規表現で検索します（正規表現が無効な場合は、大文字と小文字を区別しない部分文字列検索にフォールバックします）。単純なロール／タイトルのフィルターでは精度が足りない場合に使用してください。
• get_ui_tree — コンテナーも含め、プロセスのアクセシビリティツリー全体をたどり、後続の呼び出しに使える安定した要素 ID を割り当てます。list_elements／find_element(s) より負荷は大きいですが、構造／階層を取得できる唯一のツールです。
• ax_tree_augmented — get_ui_tree と同様ですが、OCR を 1 回実行し、OCR から得たラベルを、ネイティブのラベルを持たない AX ノードに幾何学的に対応付けます。ネイティブの AX ツリーが疎でラベルが付いていない Electron／Chromium／Canvas アプリで、特に使用してください。OCR を実行するため負荷の大きい選択肢なので、まず get_ui_tree を試し、ラベルのないノードが返された場合にこちらを使用してください。

セキュリティモデル

• ファイルを書き込むツール（capture_*、ocr_screen）は、厳格な許可リストに基づいて output_path を検証します。許可されるのは、ユーザー専用の一時ディレクトリ（NSTemporaryDirectory()）と ~/Desktop、~/Documents、~/Downloads、~/Pictures のみです。リダイレクトを防ぐため、対象パスにあるシンボリックリンクは拒否されます。/tmp はユーザー間で共有され、TOCTOU の隙が生じるため、意図的に除外されています。
• browser_eval_js の AppleScript における文字列補間では、JSON.stringify を介してユーザーコードを (0, eval)(…) でラップするため、引用符／改行／Unicode によってラッパーから抜け出すことはできません。
• ネットワーク呼び出しはありません。すべてローカルのシステム連携です。
• パスワードフィールドは指示ではなく、コードによって操作対象外になっています。ロールまたはサブロールが AXSecureTextField のフィールドでは、値も長さも返されません。また、要素への書き込み、text_* による編集、act、対象を指定しない type_text、およびそのようなフィールドにフォーカスがある間の press_key、press_key_sequence、key_down によるテキストキーや Cmd+V など、すべての書き込み経路が reason: secure_field で拒否されます。そのようなフィールドにフォーカスがある間は、メニューバーやコンテキストメニューの項目（Paste、Start Dictation、Emoji & Symbols）も押せません。ポップアップやコンボボックスのオプションメニューは引き続き使用できます。ナビゲーションキー（Tab、Return、Escape、矢印キー）は引き続き機能するため、エージェントはフィールドの操作をユーザーに引き継げます。browser_eval_js は任意のページ JavaScript を実行するため、このガードの対象外です。

現在のリリースで確認済みの状況

範囲	状態
単体テスト／統合テストスイート	swift test。ローカルと CI（macos-15）で、すべて成功しています。ci.yml をご覧ください
実際のツールの検証	実行中のバイナリに対して、実際の MCP stdio 経由で一部のツールをエンドツーエンドでテストし、すべて成功しています
破壊的なツール（volume、dark mode、force_quit_app、drag_and_drop、file_dialog_*）	元に戻せる方法で実際に動作することを確認済みです
コード署名	Hardened Runtime を有効にした Developer ID Application（A3W973JZ49）
Apple の公証	Apple Notary Service により承認済みで、チケットをステープル済みです。spctl では source=Notarized Developer ID と表示されます
Gatekeeper の動作	com.apple.quarantine xattr が設定された状態で展開・起動し、右クリックからの「開く」は不要でした
MCP Registry	io.github.AdelElo13/mac-control-mcp として公開済みです（現在のバージョンは server.json をご覧ください）。ワンクリックでインストールできる .mcpb バンドルとして配布されています
アーキテクチャ	ユニバーサルバイナリ（arm64 + x86_64）。Intel 用スライスは問題なくコンパイルできますが、実際の Intel ハードウェアでの実行は未検証です
move_window_to_display	2 台以上のディスプレイ環境が必要なため、スキップしています

未テストの経路に遭遇した場合は、再現手順を添えて Issue を作成してください。迅速に修正します。

注意事項

• クロスオリジンの iframe では browser_eval_js がブロックされます。 これはツールの制限ではなく、同一オリジンポリシーによるものです。別オリジンの埋め込み iframe 内のコンテンツには、AX 座標または合成 CGEvents を使用してください。
• 初回起動時の TCC プロンプトは避けられません。 macOS では、初回に画面収録、アクセシビリティ、Apple Events の許可をユーザーが付与する必要があります。Info.plist の使用目的の説明文により、許可ダイアログには明確な理由が表示されますが、システム設定で一度「許可」をクリックする必要があります。

開発

# Run the test suite
swift test

# Build without packaging
swift build -c release

# Live probe the running binary via MCP stdio
python3 scripts/mcp-sweep.py  # if included

ライセンス

MIT — LICENSE をご覧ください。

コントリビューション

Issue とプルリクエストを歓迎します。特に、厳しい視点でのレビューを歓迎します。リリース前には、これまでに外部レビューを 11 回実施しています。