mcp-ios

mcp-ios

iPhone/iPad を操作する Model Context Protocol サーバーです。mcp-android に対応する iOS 版です。まずお読みください：iOS は Android や macOS よりも根本的に制限が厳しいため、このサーバーは実際の UI を制御する唯一の正規ルートを採用しています。

現状について

標準状態の iPhone では、Android のユーザー補助サービス（または macOS）のように、バックグラウンドアプリが他のアプリを表示・操作することはできません。Apple のサンドボックスがこれを禁止しています。そのため、Mac や Android 向けのもののような、デバイス上で動作する「iOS 操作」エージェントは存在しません。利用可能な方法を、機能の高い順に示します。

方法	制御レベル	必要なもの	備考
Appium + WebDriverAgent (XCUITest) ✅ (このサーバー)	UI 全般：タップ、入力、スワイプ、要素の読み取り、スクリーンショット、アプリの起動	Xcode を搭載した Mac、USB（または同一ネットワーク）で接続した iPhone、デバイス用に署名された WDA	本格的な「スマートフォン操作」です。自動化／QA 向けに構築されており、自分のデバイスで使う個人用エージェントに最適です。
Shortcuts	ユーザー定義アクションの実行（アラームの設定、メッセージの送信、切り替え）	Shortcuts アプリ、URL／x-callback ブリッジ	任意の UI 操作はできませんが、安全で特定の操作に適しています。ここでは run_shortcut 経由で公開されています。
MDM	ポリシー／構成、アプリのインストール	登録	デバイス管理用であり、対話的な制御には使えません。

このサーバーは Appium/WDA ルートを実装しています。Mac 上で動作し、ローカルの Appium サーバーを介して、テザリングされた iPhone 上の WebDriverAgent を操作します。また、スイート内の他のサーバーと同じ、安全性をデフォルトとする MCP の構成を公開します。デバイスがテザリングされていない場合は、set_alarm のような操作も Shortcuts（run_shortcut）経由で実行できます。

何も接続せずに iPhone 自体から 操作したい場合、iOS ではできません。その使い方には Fold 7 で mcp-android を使用するか、ここで提供される Shortcuts の機能をお使いください。

セットアップ（Appium ルート）

brew install node
npm i -g appium
appium driver install xcuitest
# Xcode + command line tools installed; sign WebDriverAgent to your device once (Xcode)
# Connect the iPhone by USB, Trust the Mac, enable Developer Mode on the device
appium        # starts the Appium server (default http://127.0.0.1:4723)

サーバーは最初のツール呼び出し時に 遅延して XCUITest セッションを作成します。そのため、Appium やデバイスが起動する前でもサーバーを開始できます。デバイスが必要な最初の呼び出しで接続できない場合は、「appium を起動／WDA に署名／デバイスを接続」という明確なメッセージが返されます。

セキュリティモデル

懸念事項	フラグ	デフォルト	効果
サーバーで何ができますか？	IOS_MODE	read-only	read-only では検査のみが可能です。read-write では UI 操作が追加され、admin ではアプリ管理が追加されます。モードの権限を超えるツールは登録されません。
対象となるアプリはどれですか？	IOS_APP_ALLOWLIST	(すべて)	設定すると、ほかのバンドル ID の起動や管理は拒否されます。
常に読み取り専用となるアプリはどれですか？	IOS_PROTECTED_APPS	com.apple.Preferences, com.apple.springboard	検査や起動はできますが、終了、リセット、アンインストールはできません。
アプリのインストール／終了／リセットはできますか？	IOS_ALLOW_MANAGE	false	管理ツールにはこの設定と admin モードの両方が必要です。そうでない場合、ツールは公開すらされません。
インタラクティブな確認	(自動)	—	terminate_app と reset_app の実行前に、MCP エリシテーションを通じて、対象のバンドル ID を人間が承認するよう求めます。エリシテーションに対応していないクライアントでは、代わりに IOS_ALLOW_MANAGE のゲートが適用されます。
デバイスに触れずにプレビューする	IOS_DRY_RUN	false	書き込み／管理ツールは検証して意図をログに記録し、その後に戻ります。
監査証跡	IOS_AUDIT_LOG	true	保護対象の操作ごとに JSON の行を stderr に出力します。

接続設定：IOS_APPIUM_URL（デフォルトは http://127.0.0.1:4723）、IOS_UDID（対象デバイス）、IOS_BUNDLE_ID（任意のデフォルトアプリ）。すべての変数については .env.example を、クライアントごとの詳細なインストールガイドについては docs/CLIENTS.md を参照してください。

ツール

読み取り（read-only 以上）：list_targets、device_info、screenshot、page_source（要素ツリー）、current_app、list_apps

書き込み（read-write 以上）：tap、swipe、input_text、press_button（ホーム／音量）、launch_app、open_url、run_shortcut（ショートカット経由）

管理（admin + IOS_ALLOW_MANAGE）：install_app、terminate_app、reset_app（後者の2つはエリシテーションで確認します。保護対象アプリは拒否されます）

screenshot は MCP の画像コンテンツブロックを返すため、エージェントは操作する前に画面を確認できます。

クイックスタート — エージェントに追加する

npm で @dockndevai/mcp-ios として公開されています。クローンやビルドは不要です。MCP クライアントが npx を使って必要に応じて実行します。Appium サーバーが稼働している Mac 上で実行する必要があります。まずは read-only モードで開始してください。

Claude Code（CLI）

claude mcp add ios -e IOS_APPIUM_URL="http://127.0.0.1:4723" -e IOS_MODE="read-only" -- npx -y @dockndevai/mcp-ios

Claude Desktop · Cursor · Windsurf — 同じブロックを claude_desktop_config.json、.cursor/mcp.json、または ~/.codeium/windsurf/mcp_config.json に追加します。

{
  "mcpServers": {
    "ios": {
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-ios"
      ],
      "env": {
        "IOS_APPIUM_URL": "http://127.0.0.1:4723",
        "IOS_MODE": "read-only"
      }
    }
  }
}

VS Code（GitHub Copilot、Agent モード） — .vscode/mcp.json に追加します。

{
  "servers": {
    "ios": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-ios"
      ],
      "env": {
        "IOS_APPIUM_URL": "http://127.0.0.1:4723",
        "IOS_MODE": "read-only"
      }
    }
  }
}

プロンプトの例

• 「スマートフォンのスクリーンショットを撮って、画面に何が表示されているか教えてください。」
• 「Safari を開いて、news.ycombinator.com に移動してください。」（read-write が必要です）
• 「『おはよう』ショートカットを実行してください。」（read-write が必要です）

ソースから実行する（開発）

npm install
npm run build
node dist/index.js   # with the environment variables set, and `appium` running

開発

npm run dev
npm test          # security policy + elicitation confirmation (pure; no device needed)
npm run typecheck

ポリシーとエリシテーションのテストは純粋なテストで、どこでも実行できます。Mac + Xcode + 署名済み WDA + 接続された iPhone がなければ、デバイスを操作する経路のスモークテストはできないため、実際のデバイス環境を使って開発します。

公開

このサーバーには、公式 MCP レジストリ用の server.json と、npm の所有権検証用の mcpName が含まれています。npm への公開、および MCP レジストリ、Smithery、Glama、Cursor、PulseMCP への掲載については、PUBLISHING.md を参照してください。

ライセンス

MIT