Mobai Mcp

MobAI MCP Server

MobAI 用の MCP（Model Context Protocol）サーバーです。AI を活用したモバイルデバイスの自動化を実現します。AI アシスタント（Claude Code、Cursor、Windsurf、Cline、その他の MCP 対応ツール）から、単一の DSL 優先インターフェースを通じて Android および iOS のデバイス、エミュレーター、シミュレーターを操作できます。

仕組み

デバイスの操作はすべて、主要なツールである execute_dsl を通じてまとめて実行されます。タップ、スワイプ、入力などの細かなツールを多数公開する代わりに、サーバーは述語、アサーション、待機、条件分岐を含む一連のアクションを記述した JSON スクリプトを受け取ります。これにより、ラウンドトリップを減らし、再試行や失敗時の戦略をサーバー側に記述できます。

デバイスの検出、スクリーンショット、アプリ管理、.mob テストファイルの実行には、少数の補助ツールを使用します。

前提条件

• Node.js 18+
• ローカルで実行中の MobAI デスクトップアプリ（HTTP API は 127.0.0.1:8686）
• 接続済みの Android または iOS デバイス、エミュレーター、あるいはシミュレーター

インストール

Claude Code

claude mcp add mobai -- npx -y mobai-mcp

Cursor

.cursor/mcp.json に追加します：

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

Claude Desktop

（macOS の場合）~/Library/Application Support/Claude/claude_desktop_config.json に追加します：

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

Windsurf / Cline / その他の MCP クライアント

サーバーは stdio を使用します。クライアントの汎用 MCP 設定を使用してください：

{
  "command": "npx",
  "args": ["-y", "mobai-mcp"]
}

ツール

デバイス管理

ツール	説明
list_devices	接続されている Android および iOS デバイスをすべて一覧表示します
get_device	特定のデバイスの詳細を取得します
start_bridge	デバイス上で自動化ブリッジを開始します（操作前に必要です）
stop_bridge	自動化ブリッジを停止します
claim_device	このセッションでデバイスを排他的に使用する権利を取得します（通常は省略可能です。未取得のデバイスを操作すると、自動的に取得されます）
release_device	このセッションが保持しているデバイスリースを一つまたはすべて解放します

スクリーンショット

ツール	説明
get_screenshot	LLM による視覚分析用の高速で低画質なスクリーンショットを取得します（縮小される場合があり、レスポンスにはスケール係数が含まれます）
save_screenshot	レポート、デバッグ、共有用に高画質の PNG をディスクに保存します

アプリ

ツール	説明
list_apps	デバイスにインストールされているアプリを一覧表示します
install_app	ローカルファイルパスから .apk または .ipa をインストールします
uninstall_app	バンドル ID またはパッケージ名を指定してアプリをアンインストールします
debug_app	アプリをデバッグモードで起動し、標準出力と標準エラーをログファイルに書き込みます

自動化

ツール	説明
execute_dsl	主要なツールです。 DSL のステップをまとめて実行します。タップ、入力、スワイプ、観察、アサーション、Web 自動化、メトリクス、画面録画などに対応しています。

テスト管理

テストは、プロジェクトディレクトリ内のディスクにある .mob ファイルです。アシスタントのファイルシステムツールを使用して、これらを直接読み取り、書き込み、編集できます。MobAI は変更を監視し、UI をリアルタイムで更新します。MCP が必要なのは、プロジェクトの検出とテストの実行のみです。

ツール	説明
test_get_active	アクティブなテストプロジェクトのディレクトリと、その .mob ケースを取得します
test_list_projects	既知のテストプロジェクトディレクトリと、その .mob ケースをすべて一覧表示します
test_run	デバイス上で .mob テストケースを実行します（project_dir + case_path + device_id。${name} の置換用に params を任意で指定できます）

リソース

デバイスを操作する前に、以下を必ず読んでください。DSL スキーマ、アクション一覧、述語、失敗時の戦略、.mob の構文について説明しています。

URI	用途
mobai://reference/device-automation	デバイスの操作方法 — ガイド、すべての DSL アクション、述語、失敗時の戦略
mobai://reference/testing	テストのワークフロー、ルール、エラーの修正方法、.mob スクリプトの構文

例

iOS の「設定」アプリを開き、「Wi-Fi」に移動して、トグルがあることを確認します。

{
  "version": "0.2",
  "steps": [
    {"action": "open_app", "bundle_id": "com.apple.Preferences"},
    {"action": "wait_for", "predicate": {"text": "Settings"}, "timeout_ms": 3000},
    {"action": "tap", "predicate": {"text_contains": "Wi-Fi"}},
    {"action": "wait_for", "predicate": {"type": "switch"}, "timeout_ms": 3000},
    {"action": "assert_exists", "predicate": {"type": "switch"}},
    {"action": "observe", "include": ["ui_tree"]}
  ]
}

これを commands 引数（JSON 文字列）として、list_devices から取得した device_id とともに execute_dsl に渡します。

トラブルシューティング

「Connection refused」／「Could not reach the MobAI desktop app」 — MobAI デスクトップアプリがインストールされ、実行中であること、および API に http://127.0.0.1:8686 からアクセスできることを確認してください。まだインストールしていない場合は、https://mobai.run/download からダウンロードしてインストールしてください。

「Bridge not running」 — まず start_bridge を呼び出してください。iOS ブリッジの起動には最大 1 分ほどかかる場合があります。

スクリーンショットが表示されない — get_screenshot はデフォルトで /tmp/mobai/screenshots/ に保存し、ファイルパスを返します。アシスタントのファイル読み取り機能を使って表示してください。DSL の observe によるスクリーンショットはレスポンスから抽出され、同じディレクトリに保存されます。

開発

git clone https://github.com/MobAI-App/mobai-mcp.git
cd mobai-mcp
npm install
npm run build
node dist/index.js

ライセンス

Apache 2.0 — LICENSE を参照してください。