iPhone Mirror

iphone-mirror-mcp

あらゆる LLM から実機の iPhone を操作できます。

macOS に標準搭載された iPhone Mirroring アプリを通じて実機の iPhone を操作し、Xcode の開発テストを自動化する MCP サーバーです。シミュレーターやデバイスでビルド、テスト、インストール、起動を行い、ミラーリングされた画面上でタップ、スワイプ、文字入力、OCR を使ってアプリを操作できます。

脱獄は不要です。iPhone へのインストールも不要です。XCUITest のターゲットも不要です。

run_on_iphone (build → install → launch on the paired iPhone)
   → screenshot / read_screen / tap / paste_text     drive the app on-device
   → wait_for_text / tap with expect / sim_log       assert what the user sees

63 個のツール。 Claude、GPT、Gemini、ローカルモデルなど、stdio 経由で MCP を使用するあらゆるモデルで動作します。

---

クイックスタート

git clone https://github.com/nickatnight96/iphone-mirror-mcp.git
cd iphone-mirror-mcp
./install.sh

インストーラーはお使いのマシンを確認し、リリースバイナリをビルドして、権限を最初から最後まで検証し、クライアント用の正確な設定を表示します。

次に、Claude Code の場合：

claude mcp add --scope user iphone-mirror -- ~/.local/bin/iphone-mirror-mcp

その他の MCP クライアントの場合：

{
  "mcpServers": {
    "iphone-mirror": {
      "command": "/Users/YOU/.local/bin/iphone-mirror-mcp"
    }
  }
}

モデルに次のように依頼します：

iPhone のスクリーンショットを撮って、どのアプリが開いているか教えてください。

または、クライアントが MCP バンドルをインストールでき、ツールチェーンを省略したい場合は、 最新のリリース から .mcpb バンドルを取得してください （注意事項をご覧ください。アドホック署名されていますが、公証はされていません）。

→ 導入ガイド全文 · クライアント別の設定

必要条件

• iPhone Mirroring を搭載した macOS 15 以降と、ペアリング済みの iOS 18 以降の iPhone（近くにあり、ロック状態で、同じ Apple Account を使用）
• Xcode — xcode_*、device_*、sim_* ツールを使用する場合に必要
• アクセシビリティと画面収録の権限を、サーバーを起動するアプリ（ターミナル、またはクライアントをホストするデスクトップアプリ）に付与してください — 詳細

すべてをまとめて確認するには：

iphone-mirror-mcp doctor

4 種類の権限をすべてテストし、実際のフレームをキャプチャして、macOS が単に権限フラグを読み取るだけでなく、合成入力を実際に送信していることを確認します。ほかの原因を疑う前に実行してください。

できること

セッションとヘルスチェック	status、doctor、mirror_launch、mirror_restart
画面を見る	screenshot、annotated_screenshot（すべての要素を枠で囲み、番号を付けます）、read_screen（タップ可能な中心座標を含む OCR）、find_text、find_image、record_screen
適切に待機する	wait_for_text、wait_for_screen_change、scroll_to
入力	tap（expect による検証付き）、double_tap、long_press、swipe、drag、type_text、paste_text（クリップボード経由で絵文字／CJKを入力）、read_clipboard、press_key、shake、batch
移動する	home、app_switcher、spotlight、launch_app、open_url
通知	notifications、notification_click
Xcode	xcode_list、xcode_build、xcode_test、xcresult_attachments
実機	run_on_iphone、devices、device_install、device_launch、device_info、device_apps、device_uninstall
シミュレーター	run_on_sim に加えて、simctl の全機能一式 — プッシュ通知、GPS、プライバシー権限の付与、ステータスバー、外観、ログ、メディア

→ ツールの完全なリファレンス — パラメーター付きの全 63 種。サーバー独自のカタログから生成されるため、内容がずれることはありません。

座標の仕様

すべての x／y は、最新のスクリーンショット上のピクセル座標で、原点は左上です。入力時にウィンドウの境界を再取得し、ピクセル座標を現在の境界に比例して対応付けるため、スクリーンショットの撮影後にウィンドウが移動またはサイズ変更されても、正しい位置にタップできます。

ドキュメント

はじめに	インストール → 権限設定 → 最初のタップ
クライアントの接続	Claude Code、Claude Desktop、Cursor、VS Code、Zed、Codex、Windsurf
ツールリファレンス	全 63 種のツールとそのパラメーター
レシピ	アプリの操作、デバイス上でのテストループ、通知、バッチ処理
トラブルシューティング	症状 → 原因 → 解決策
アーキテクチャ	入力が実際にどのように iPhone に届くか
制限事項	実際にできないこと

既知の制限事項

推測ではなく、テスト済みです。全リストでその理由を説明しています。

• ピンチと回転は再現できません。 トラックパッドのジェスチャーは CGEvent パイプラインを通らず、物理的なピンチ操作中はイベントタップに何も届かないため、再現する手段がありません。
• 一度に操作できる iPhone は 1 台です — デバイス切り替え用のスクリプト可能なメニューはありません。
• iPhone のロックを解除するか、持ち上げると、セッションは一時停止します。 これは Apple の設計によるもので、再開するには再びロックする必要があります。
• アクセシビリティツリーはありません — 要素のモデルには OCR とテンプレートマッチングを使用します。Face ID、コントロールセンター、ハードウェアボタンにはアクセスできず、DRM コンテンツをキャプチャすると画面は黒くなります。

セキュリティ

このサーバーは、ミラーリング中に Mac とペアリングされている iPhone の画面を見たり、操作したりできます。ロック解除済みの iPhone をモデルに渡すのと同じように扱ってください。 信頼できるクライアントからのみ実行してください。

iPhone は物理的に持ち上げられるかロックを解除された瞬間にセッションをロックします。これは実際に機能する緊急停止手段です。paste_text はテキストを一時的に Mac のクリップボードに置き、元の内容に戻します。read_clipboard はクリップボードを読み取ります。

信頼モデルと脆弱性の報告方法については、SECURITY.md を参照してください。

コントリビューション

Issue やプルリクエストを歓迎します。CONTRIBUTING.md を参照してください。

scripts/run_tests.sh                    # build + unit/protocol tests + CLI smoke
MIRROR_MCP_LIVE=1 scripts/run_tests.sh  # + live tests (real window, capture, input)

ライセンス

MIT