Mobile Device Mcp

mobile-device-mcp

AI コーディングアシスタント（Claude Code、Cursor、Windsurf）に、モバイルデバイスを見て操作する機能を提供する MCP サーバーです。スクリーンショット、UI の検査、タッチ操作、AI による視覚分析、Flutter ウィジェットツリーの検査、動画録画、テスト生成に対応する 49 個のツールを備えています。

AI アシスタントはコードを読めても、スマートフォンの画面を見ることはできません。このサーバーがその問題を解決します。

このサーバーを選ぶ理由

問題点

ウェブ開発者にはブラウザーの DevTools、Playwright、Puppeteer があり、AI アシスタントは画面をクリックして、スクリーンショットを撮り、修正を検証できます。一方、モバイル開発者は手作業でスクリーンショットを撮り、ログをコピーし、画面に何が表示されているかを説明せざるを得ません。AI とデバイスの間を取り持つ人間の仲介役になっています。

このサーバーでできること

Developer: "The login button doesn't work"

Without this tool:                    With this tool:
  1. Manually screenshot              1. AI calls take_screenshot -> sees the screen
  2. Paste into AI chat               2. AI calls smart_tap("login button") -> taps it
  3. AI guesses what's wrong          3. AI calls verify_screen("error message shown") -> sees result
  4. Apply fix, rebuild               4. AI calls visual_diff -> confirms fix worked
  5. Repeat 4-5 times                 5. Done.

クイックスタート

インストール

npx mobile-device-mcp

グローバルインストールは不要です。npx から直接実行できます。

前提条件

• Node.js 18 以降
• ADB 経由で接続された Android デバイス／エミュレーター
• ADB がインストールされていること（Android SDK Platform Tools）

セットアップ（初回のみ、30秒）

1. Google AI キーを取得します（無料枠あり）：aistudio.google.com/apikey

2. プロジェクトのルートに .mcp.json を追加します：

macOS / Linux：

{
  "mcpServers": {
    "mobile-device": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mobile-device-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key"
      }
    }
  }
}

Windows：

{
  "mcpServers": {
    "mobile-device": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "mobile-device-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key"
      }
    }
  }
}

Pro ライセンスキーを使用する場合（Pro の購入後）：

{
  "mcpServers": {
    "mobile-device": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mobile-device-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key",
        "MOBILE_MCP_LICENSE_KEY": "MDMCP-XXXXX-XXXXX-XXXXX-XXXXX"
      }
    }
  }
}

{
  "mcpServers": {
    "mobile-device": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "mobile-device-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key",
        "MOBILE_MCP_LICENSE_KEY": "MDMCP-XXXXX-XXXXX-XXXXX-XXXXX"
      }
    }
  }
}

3. そのディレクトリからAI コーディングアシスタントを開きます。これで完了です。

サーバーは自動的に起動・停止するため、手動で実行する必要はありません。AI アシスタントが MCP プロトコルを介してバックグラウンドプロセスとして管理します。

動作確認

Claude Code： /mcp と入力すると、mobile-device: Connected と表示されます。

Cursor： 設定の MCP パネルを確認してください。

あとはスマートフォンに話しかけるだけです。

You: "Open my app, tap the login button, type [email protected] in the email field"
AI:  [takes screenshot -> sees the screen -> smart_tap("login button") -> smart_type("email field", "[email protected]")]

You: "Find all the bugs on this screen"
AI:  [analyze_screen -> inspects layout, checks for overflow, missing labels, broken states]

You: "Navigate to settings and verify dark mode works"
AI:  [smart_tap("settings") -> take_screenshot -> smart_tap("dark mode toggle") -> visual_diff -> reports result]

テストスクリプトも、手動のスクリーンショットも不要です。やりたいことを自然な言葉で伝えるだけです。

あらゆる AI コーディングアシスタントに対応

いずれも同じ JSON 設定を使います。エディターに対応するファイルに配置するだけです。

あらゆるプロジェクトに導入

.mcp.json を Flutter、React Native、Kotlin、Swift など、任意のモバイルプロジェクトにコピーすると、そのディレクトリ内で AI アシスタントがデバイスの機能を活用できるようになります。グローバルインストールは不要です。

Free と Pro の比較

Free（14 個のツール）-- ライセンスキーは不要

Pro（追加で 35 個のツール）-- ₹499/月

Pro ライセンスを取得 -- 49 個すべてのツールを利用できます。お支払い後、1 時間以内にライセンスキーがメールで届きます。.mcp.json に追加してください。

{
  "mcpServers": {
    "mobile-device": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mobile-device-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key",
        "MOBILE_MCP_LICENSE_KEY": "your-license-key"
      }
    }
  }
}

AI による視覚分析（12 個のツール）

AI の視覚認識（Claude または Gemini）を使って、画面上の内容を理解します。

Flutter ウィジェットツリー（10 個のツール）

Dart VM Service Protocol 経由で、実行中の Flutter アプリに接続します。すべてのウィジェットをソースコード上の位置（file:line）に対応付けます。

iOS シミュレーター（4 個のツール）

macOS 専用です。xcrun simctl 経由で iOS シミュレーターを操作します。

動画録画（2 個のツール）

テスト生成（3 個のツール）

アプリ管理（4 個のツール）

パフォーマンス

このサーバーは、レイテンシーと AI トークンコストを最小限に抑えるよう最適化されています。

• 4 段階の要素検索：コンパニオンアプリ（即時） -> ローカルのテキスト一致（1 ミリ秒未満） -> キャッシュ済み AI -> 新規 AI。smart_tap は、単純な AI 呼び出しより 35 倍高速です（205 ミリ秒対 7.6 秒）。
• コンパニオンアプリ：AccessibilityService ベースの Android アプリが、UIAutomator の 2448 ミリ秒に対して 105 ミリ秒（23 倍高速）で UI ツリーを提供します。初回使用時に自動インストールされます。
• スクリーンショット圧縮：AI ツールは JPEG q=60、400w に自動圧縮します。AI の品質を損なうことなく 89% 小さくなります（251KB -> 28KB）。
• 並列キャプチャ：スクリーンショットと UI ツリーを Promise.all() で同時に取得します。
• TTL キャッシュ：5 秒間のキャッシュにより、ツールを連続して使用した際の重複した ADB 呼び出しを回避します。

環境変数

アーキテクチャ

src/
|-- index.ts              # CLI entry point (auto-discovery, env config)
|-- server.ts             # MCP server factory
|-- license.ts            # License validation and tier gating
|-- types.ts              # Shared interfaces
|-- drivers/android/      # ADB driver (DeviceDriver implementation)
|   |-- adb.ts            # Low-level ADB command wrapper
|   |-- companion-client.ts # TCP client for companion app
|   +-- index.ts          # AndroidDriver class (4-strategy UI element retrieval)
|-- drivers/flutter/      # Dart VM Service driver
|   |-- index.ts          # FlutterDriver (discovery, inspection, source mapping, hot reload)
|   +-- vm-service.ts     # JSON-RPC 2.0 WebSocket client (DDS redirect handling)
|-- drivers/ios/          # iOS Simulator driver (macOS only)
|   |-- index.ts          # IOSSimulatorDriver via xcrun simctl
|   +-- simctl.ts         # Low-level simctl command wrapper
|-- tools/                # MCP tool registrations (free + pro gating)
|   |-- device-tools.ts   # Device management
|   |-- screen-tools.ts   # Screenshots & UI inspection
|   |-- interaction-tools.ts # Touch, type, keys
|   |-- app-tools.ts      # App management
|   |-- log-tools.ts      # Logcat
|   |-- ai-tools.ts       # AI-powered tools
|   |-- flutter-tools.ts  # Flutter widget inspection
|   |-- ios-tools.ts      # iOS simulator tools
|   |-- video-tools.ts    # Screen recording
|   +-- recording-tools.ts # Test generation
|-- recording/            # Test script generation
|   |-- recorder.ts       # ActionRecorder (records MCP tool calls)
|   +-- generator.ts      # TestGenerator (TypeScript/Python/JSON output)
|-- ai/                   # AI visual analysis engine
|   |-- client.ts         # Multi-provider client (Anthropic + Google)
|   |-- prompts.ts        # System prompts & UI element summarizer
|   |-- analyzer.ts       # ScreenAnalyzer orchestrator (caching, parallel capture)
|   +-- element-search.ts # Local element search (text/alias matching, no AI needed)
+-- utils/
    |-- discovery.ts      # ADB auto-discovery
    +-- image.ts          # PNG parsing, JPEG compression, bilinear resize

companion-app/            # Android companion app (Kotlin)
                          # AccessibilityService + TCP JSON-RPC for fast UI tree

ロードマップ

• iOS 物理デバイスのサポート
• マルチデバイスのオーケストレーション
• CI/CD 統合
• クラウドデバイスファームのサポート

テスト済み環境

• デバイス：Pixel 8（Android 16）、Samsung Galaxy シリーズ、Android エミュレーター
• アプリ：Telegram、Instagram、Spotify、WhatsApp、YouTube、Chrome、Settings、Flutter アプリ
• AI プロバイダー：Google Gemini 2.5 Flash、Anthropic Claude
• プラットフォーム：Windows 11、macOS（iOS シミュレーター）
• 接続：USB およびワイヤレス ADB

ライセンス

Business Source License 1.1

• 個人利用および非商用利用は無料です
• 商用利用には有料ライセンスが必要です
• 2030年3月23日に Apache 2.0 に切り替わります

詳細な条件については、LICENSE をご覧ください。