Mobile MCP Ai

🚀 Mobile MCP AI

移动端の自動化MCP Serverです。Cursor AIにモバイルデバイスの制御機能を提供し、Android/iOSをサポートします。

🚀 クイックスタート

1. Cursor MCPの設定

~/.cursor/mcp.json（macOS/Linux）または %APPDATA%\Cursor\mcp.json（Windows）を編集します。

{
  "mcpServers": {
    "mobile-automation": {
      "command": "python",
      "args": ["-m", "mobile_mcp.mcp.mcp_server"],
      "cwd": "/path/to/your/project"
    }
  }
}

💡 モード切り替え（オプション）：

• デフォルトの完全版（39個のツール）：テストスクリプトの生成、操作履歴、動的設定などが含まれます ⭐ おすすめ
• 簡易版（32個のツール）："env": {"MOBILE_MCP_MODE": "simple"} を追加します
  • ⚠️ 簡易版はテストスクリプトの生成（mobile_generate_test_script）をサポートしていません
  • 基本的な操作のみが必要なシーンに適しています

📝 設定の説明：

• "cwd"：プロジェクトのルートディレクトリで、テストスクリプトはこのディレクトリの tests/ 以下に保存されます
• AI機能：Cursorは組み込みのAIを自動的に使用し、追加の設定は必要ありません
• その他のAIプラットフォーム：必要に応じて 設定ガイド を参照してください

2. デバイスの接続

# Androidデバイス
adb devices  # デバイスが表示されることを確認
# iOSデバイス（オプション）
pip install mobile-mcp-ai[ios]

3. Cursorの再起動

設定が完了したら、Cursorを完全に終了してから再起動します。

4. 使用開始

方法1：基本ツール（要素を明示的に指定）

@MCP ログインをテストしてください：
1. すべての要素をリストアップする
2. resource-idが "com.app:id/login_btn" の要素をクリックする
3. resource-idが "com.app:id/username" の要素に "admin" を入力する
4. スクリーンショットを保存する

方法2：Cursor AIにスクリーンショットを分析させる（おすすめ）

@MCP ログインをテストしてください：
1. 現在の画面をスクリーンショットする
2. 分析してから「ログイン」ボタンをクリックする
3. 「ユーザー名」入力欄に "admin" を入力する
4. スクリーンショットで確認する

Cursor AIが自動的にスクリーンショットを撮り、画像を分析し、要素の座標を見つけて操作します！

✨ 主な機能

🎯 AI機能の選択可能化

• 基本モード：AIキーの設定は不要で、Cursor AIがすべてのインテリジェント機能を提供します
• インテリジェントモード：AIキーをオプションで設定でき、自動化テストプラットフォームの構築に適しています
• ゼロコストでの開始：基本ツールは完全に無料で、追加のAI API料金はかかりません
• 柔軟な選択：使用シーンに応じてAI機能を自由に有効化するかどうかを選択できます

📦 ツールの特性

• 39個のツール：要素操作、デバイス管理、テスト生成などをカバーしています
• 操作の録画：操作を自動的に記録し、1クリックでpytestテストスクリプトを生成します
• 双プラットフォームサポート：AndroidとiOSで統一されたインターフェースを提供します
• インテリジェントな検証：ボタン操作が実際に有効になったかどうかを自動的に検証します

🤖 Cursor AIとの深い統合

• MCPプロトコル：Model Context Protocolに基づいて、シームレスに統合されています
• 39個のツール：豊富なモバイル操作ツール（完全版）
• ビジュアル認識：Cursor AIが直接スクリーンショットを分析して操作できます
• テスト生成：AI操作後に1クリックでpytestスクリプトを生成します

📦 インストール

基本インストール（推奨、Cursorユーザーの最初の選択肢）

# コア依存のみを含み、Cursor AIがすべてのインテリジェント機能を提供します
pip install mobile-mcp-ai

✅ 適用シーン：

• Cursorで使用する場合（最も一般的）
• 32個の基本ツールで十分な場合
• 追加のAI APIキーが不要な場合

完全インストール（自動化プラットフォームの構築）

# 追加でAI SDKをインストール：通義千問、OpenAI、Claude
pip install mobile-mcp-ai[ai]

✅ 適用シーン：

• 独立した自動化テストプラットフォームを構築する場合
• CI/CDでインテリジェントツールを使用する場合
• Cursorから独立して実行する必要がある場合

💡 違いの説明：基本版には dashscope、openai、anthropic などのAI SDKが含まれておらず、Cursorで使用する場合は十分です（Cursor AIがインテリジェント機能を提供します）。独立した環境でインテリジェントツールを実行する必要がある場合のみ、完全インストールが必要です。

最新バージョンにアップグレード

⚠️ 重要：古いバージョンを既にインストールしている場合は、強くお勧めします v2.1.0にアップグレードしてください！

# 最新バージョンにアップグレード
pip install --upgrade mobile-mcp-ai
# バージョンを確認
pip show mobile-mcp-ai

💻 使用例

シーン1：基本ツールのテスト（要素を明示的に指定）

@MCP 以下の操作を実行してください：
1. com.example.appを起動する
2. すべてのクリック可能な要素をリストアップする
3. resource-idが "com.example:id/login_btn" の要素をクリックする
4. "com.example:id/home" 要素が表示されるのを待つ
5. スクリーンショットを保存する

シーン2：Cursor AIによるビジュアル分析（インテリジェント推奨）

@MCP ログイン機能をテストしてください：
1. 現在の画面をスクリーンショットする
2. 「ログイン」ボタンを見つけてクリックする
3. もう一度スクリーンショットを撮り、「ユーザー名」入力欄を見つけて "test123" を入力する
4. 「パスワード」入力欄を見つけて "pass123" を入力する
5. 「確定」ボタンをクリックする
6. 結果をスクリーンショットで確認する

シーン3：インテリジェントツール（AIの設定が必要）

@MCP AI機能の状態を確認する
@MCP インテリジェントな方法で「ログイン」ボタンをクリックする
@MCP 「ユーザー名」入力欄に "test123" を入力する

シーン4：テストスクリプトの生成（推奨）✨ 新機能

@MCP ログイン機能をテストしてください：
1. com.example.appを起動する
2. スクリーンショットを撮り、「ログイン」ボタンを見つけてクリックする
3. 「ユーザー名」に "test123" を入力する
4. 「パスワード」に "pass123" を入力する
5. 「送信」ボタンをクリックする

@MCP 先ほどの操作のテストスクリプトを生成する

AIが自動的に完全なpytestテストスクリプトを生成します：

• ✅ あなたのプロジェクトの tests/ ディレクトリに保存されます
• ✅ インテリジェントな待機ロジック（ページの読み込み、遷移、入力）を含みます
• ✅ ポップアップを自動的に処理します（存在する場合はクリックし、存在しない場合はスキップします）
• ✅ 複数のデバイスをサポートします（デバイスIDを自動的に検出します）
• ✅ 独立して実行できます（pip install uiautomator2 pytest のみが必要）

生成されたスクリプトの例：

def test_登录(device):
    d = device
    
    # ステップ1: 「ログイン」をクリックする
    d.click(540, 338)
    time.sleep(2.0)  # ページ遷移をインテリジェントに待つ
    
    # ステップ2: ユーザー名を入力する
    d(resourceId="com.example:id/username").set_text("test123")
    time.sleep(1.5)
    
    # ステップ3: 送信をクリックする
    d.click(972, 1200)
    time.sleep(2.0)
    
    assert d(text="首页").exists()

📚 ドキュメント

• ユーザー設定ガイド - AIキーの設定、よくある質問
• 起動ガイド - 完全なインストールと設定手順
• テストスクリプトの生成 - pytestテストスクリプトを生成する方法
• 自動化動作の設定説明 - 画面の向きと自動広告の閉じるを制御する

🔧 技術詳細

📊 ツールの分類統計

🔥 よく使うツールの概要

基本操作（AI不要）

• mobile_list_elements - すべての対話可能な要素をリストアップする
• mobile_click_by_id / mobile_click_by_text - 正確なクリック
• mobile_input_text_by_id - テキストを入力する
• mobile_take_screenshot - スクリーンショットを撮る（Cursor AIに分析させるため）
• mobile_wait - 指定された時間または要素を待つ ⭐ 完全版のみ
• mobile_wait_for_element - 要素が表示されるのを待つ

インテリジェント操作（AIが必要、オプション）

• mobile_smart_click - 自然言語によるインテリジェントなクリック
• mobile_smart_input - 自然言語によるインテリジェントな入力
• mobile_analyze_screenshot - AIによるビジュアル分析
• mobile_execute_test_case - インテリジェントなテストの実行 ⭐ 完全版のみ
• mobile_generate_test_script - pytestスクリプトを生成する ⭐ 完全版のみ

デバイスとアプリケーションの管理

• mobile_list_devices - 接続されたデバイスをリストアップする
• mobile_launch_app - アプリケーションを起動する
• mobile_list_apps - インストールされたアプリケーションをリストアップする
• mobile_get_screen_size - 画面サイズを取得する

動的設定 ⭐ 完全版のみ

• mobile_configure - 待機時間、検証戦略などを調整する
• mobile_get_config - 現在の設定を確認する

📋 新しいツール：デバイス接続管理（check_connection, reconnect_device）、操作履歴管理（get_operation_history, clear_operation_history）

mobile_press_key - 「見かけ上の成功」問題を完全に解決する

問題の背景： 従来のボタン操作では、コマンドが実行されたかどうかのみをチェックし、ボタンが実際に有効になったかどうかを検証しないため、以下の問題が発生します：

• ✗ コマンドの実行成功 ≠ ボタンの有効化
• ✗ テストが合格と表示されるが、実際の操作は失敗している
• ✗ 検索ボタンが一部のアプリケーション/入力法で機能しない

インテリジェントな検証方案：

# 方法1: 検証モード（推奨、デフォルト）
await press_key("search", verify=True)
# ✅ ページの変更を自動的に検出する
# ✅ 検索ボタンが無効な場合、自動的にエンターキーを試みる
# ✅ 実際の操作結果を返す

# 方法2: 高速モード
await press_key("back", verify=False)
# ⚡ 実行後すぐに返す
# ⚠️  ボタンの効果を保証しない

動作原理：

1. 操作前のスナップショット - 現在のページの状態を記録する
2. ボタンの実行 - ボタンコマンドを送信する
3. ページの監視 - ページの変更を待ち、検出します（最大2秒）
4. インテリジェントな判断 - ページの変更が5%を超えた場合、成功と判断します
5. 検索ボタンのフォールバック - SEARCHが無効な場合、自動的にENTERを試みます

使用例：

@MCP 検索を行ってください：
1. 検索ボックスに "テスト内容" を入力する
2. 検索ボタンを押す（自動検証）

返される結果：

{
  "success": true,
  "key": "search",
  "keycode": 84,
  "verified": true,
  "page_changed": true,
  "fallback_used": false,
  "message": "検索ボタン(SEARCH)が有効になりました"
}

SEARCHボタンが無効な場合：

{
  "success": true,
  "key": "search",
  "keycode": 66,
  "verified": true,
  "page_changed": true,
  "fallback_used": true,
  "message": "検索ボタン(SEARCH)が無効で、ENTERキーが代わりに使用され、成功しました"
}

ボタンが無効な場合：

{
  "success": false,
  "key": "search",
  "verified": true,
  "page_changed": false,
  "message": "ボタンコマンドは正常に実行されましたが、ページに変更がないため、ボタンが有効になっていない可能性があります"
}

使用の提案：

パフォーマンスの比較：

• 高速モード：~0.05秒（効果を保証しません）
• 検証モード：~0.5 - 2秒（成功を保証します）
• 追加の時間：2秒未満で、信頼性を得ることができます

サポートされるボタン：

• enter / 回车 - Enterキー (keycode=66)
• search / 搜索 - 検索ボタン (keycode=84, 自動的に66にフォールバック)
• back / 返回 - 戻るボタン (keycode=4)
• home - Homeキー (keycode=3)
• 直接keycodeの数字を使用する（例：66）

デモスクリプト： python backend/mobile_mcp/examples/press_key_verification_demo.py を実行して、完全なデモを確認してください。

📊 技術スタック

• MCPプロトコル：Cursor AIとシームレスに統合されています
• UIAutomator2：Androidの自動化エンジン
• Appium：iOSの自動化サポート（オプション）
• 複数のAIサポート：通義千問、OpenAI、Claude（オプション）

📄 ライセンス

Apache License 2.0