mobile-next/mobile-mcp — 優良食堂詳しい解説

01 / 概要

何をするものか一文で言うと

ひとことでAIエージェントとLLMのためにiOS・Androidアプリとデバイスを自動操作できるMCPサーバーです。

mobile-mcpは、iOS/Androidのシミュレータ・エミュレータ・実機をMCP(Model Context Protocol)経由でLLMエージェントから操作するサーバーです。タップ・スワイプ・アプリ起動・要素一覧取得などのツールをClaude CodeやCodexなどのMCPクライアントに公開します。画像処理ではなくアクセシビリティツリーを優先的に読み取り、必要な場合のみスクリーンショットと座標に切り替える設計です。

02 / 構造

どう動くのか中核のしくみ

読み方動きの流れを図と一緒にほどきました。

src/server.tsがzodスキーマ付きのMCPツールを登録し、src/robot.tsで定義したRobotインターフェースをAndroidRobot(src/android.ts)とiOS実装(src/ios.ts、iphone-simulator.ts、webdriver-agent.ts)がそれぞれ実装します。Android側はexecFileSyncでadbを直接呼び出し、uiautomator dumpのXMLをfast-xml-parserで解析して画面要素を取得します。iOS側はxcrun simctlやWebDriverAgentのHTTP APIを叩きます。取得した要素はformat-elements.tsで「@ref Type text= label= at=x,y size=WxH」という1行テキストかJSONに整形され、LLMが読みやすい形になります。スクリーンショットを使う操作では、coordinate-mapping.tsがスクリーンショットのピクセルサイズと実画面サイズの比率を文章化し、LLMがタップ座標を正しい倍率に換算できるよう案内します。

03 / 体験

入れるとこんな体験になりますギット飯が実際にたどった順序

所要ギット飯が実際に導入・実行しながらたどった順序です。

STEP 01
npx -y @mobilenext/mobile-mcp@latestでMCPクライアントに登録すると、サーバーが起動しstdioで待ち受けます。
STEP 02
mobile_list_available_devicesを呼ぶと接続中のシミュレータ・エミュレータ・実機の一覧が返りますが、何も繋がっていなければ空になります。
STEP 03
Android機を使う場合は事前にadb devicesで端末が認識されている必要があり、未認識だとAndroidRobotのadb呼び出しがエラーで止まります。
STEP 04
mobile_list_elements_on_screenを呼ぶと、uiautomator dumpのXMLを解析した結果が「@ref Type text= label= at=x,y size=WxH」という1行形式で返ってきます。
STEP 05
mobile_take_screenshotとmobile_click_on_screen_at_coordinatesを組み合わせると、coordinate-mapping.tsが算出した倍率の説明文が添えられ、LLMはその倍率でタップ座標を換算します。
STEP 06
Docker版ではコンテナ内にadbクライアントだけが入っており、ADB_SERVER_SOCKET経由でホスト側のadbサーバーに接続するため、ホスト側のUSBデバッグ設定は省略できません。

04 / 成果物

何が手に入るのか導入後に手元に残るもの

手に入るのは、LLMエージェントがiOS/Android端末をタップ・スワイプ・アプリ起動・要素取得などで操作できるMCPツール群一式です。test/android.tsなどのテストコードを見ると、検証は実機やエミュレータの接続を前提としたPlaywrightテストで行われており、デバイス未接続時はtest.skipされる構成です。

05 / 注意

ここは先に知っておいてください先に知っておくとよいこと

正直なところ誰にでも合うとは言いにくいところです。

実機・エミュレータ・シミュレータが手元になければ何も試せず、クラウド関連ツール(mobile_login_to_cloud_providerなど)はMobile Next Cloudという別サービスとの連携が前提です。

Android側はexecFileSyncでadbコマンドを直接呼ぶ設計のため、adbのバージョンやPATH、ANDROID_HOME設定に動作が左右されます。

iOS実機やWebDriverAgent周りはmacOSとXcode環境が必須で、Windows・Linuxホスト単体では動かせません。

テストスイート自体が「デバイスが正確に1台接続されている場合のみ実行」という条件付きのため、リポジトリのコードだけでは実機での再現性までは保証できません。

06 / 結論

ギット飯の結論食べてみる価値のある一膳か

ギット飯の最終判断優良食堂

エージェントベースのモバイルQAやスクリプト操作を試したいチームに向いています。Android/iOSのロボット分離、座標換算ロジック、要素フォーマットなど実装レベルで筋が通っており設計は信頼できますが、効果は接続する端末環境に強く依存するため、導入前にadbやsimctlの環境整備が必要です。この判断はソースコードとテストの条件分岐から読み取れる内容に基づいており、実機を用意しなくても構成の妥当性は確認できます。