Mcp Android Agent Python

MCP Android Agent

このプロジェクトは、uiautomator2 を使用して Android デバイスを自動化するための MCP（Model Context Protocol） サーバーを提供します。GitHub Copilot Chat、Claude、Open Interpreter などの AI エージェントに簡単に組み込み、自然言語を通じて Android デバイスを制御できるように設計されています。

モジュール式アーキテクチャ

サーバーは、機能ごとに整理されたツールを備えたクリーンなモジュール式アーキテクチャにリファクタリングされました。

mcp-android-server-python/
├── server.py                    # Main server (61 lines - clean & focused)
├── server_original_backup.py    # Backup of original monolithic version
└── tools/                       # 🆕 Modular tools package
    ├── __init__.py             # Central registration & imports
    ├── device_tools.py         # Device connection & status tools
    ├── app_tools.py            # Application management tools
    ├── screen_tools.py         # Screen control & unlock tools
    ├── input_tools.py          # User input simulation (click, swipe, text)
    ├── inspection_tools.py     # UI inspection & screenshots
    └── advanced_tools.py       # Advanced features (toast, activity wait)

モジュール式アーキテクチャの利点

• 保守性: メインサーバーに触れることなく、ツールを簡単に追加・変更・削除できます
• 整理: ツールが機能ごとに論理的にグループ化されています
• テスト: 個々のツールモジュールを個別に単体テストできます
• 再利用性: ツールモジュールを他のプロジェクトで再利用できます
• 拡張性: 新しいツールカテゴリを別個のモジュールとして追加できます
• クリーンなコード: メインサーバーが 1321 行から 61 行に削減されました

クイックデモ

---

要件

• Python 3.13 以上
• Android Debug Bridge（adb）がインストールされ、PATH に含まれていること
• USB デバッグを有効にした Android デバイスが接続されていること
• uiautomator2 互換の Android デバイス

機能

デバイス管理

• スマートデバイス検出: 利用可能なデバイスを自動的に検出して接続します
• 包括的なデバイス情報: シリアル、解像度、バッテリー、WiFi IP、Android バージョンを取得します
• ADB 診断: ADB の可用性と接続ステータスを確認します
• ヘルスモニタリング: サーバーのヘルスチェックを内蔵しています

アプリケーション管理

• アプリの検出: インストールされているすべてのアプリケーション（システムアプリ + ユーザーアプリ）を一覧表示します
• アプリのライフサイクル制御: パッケージ名でアプリを起動、停止、強制停止します
• アプリ状態の監視: 現在のフォアグラウンドアプリとアクティビティを追跡します
• データ管理: テスト用にアプリのデータやキャッシュをクリアします

画面とディスプレイの制御

• 画面の電源管理: プログラムから画面をオン・オフにします
• スマートロック解除: 標準的な方法による自動画面ロック解除
• 画面状態の監視: 画面のアクティブ化を待機します（非同期対応）

ユーザー入力のシミュレーション

• 精密な操作: テキスト、リソース ID、コンテンツ記述によるクリック
• 高度なジェスチャー: 長押し、スワイプ、ドラッグ操作
• テキスト入力: フィールドのクリアを任意で行えるスマートなテキスト入力
• ハードウェアキー: ホーム、戻る、メニュー、音量キーをシミュレートします

UI の検査とデバッグ

• 要素の分析: UI 要素の詳細なプロパティと境界を取得します
• スクリーンキャプチャ: デバッグやドキュメント用にスクリーンショットを撮影します
• UI 階層: 画面構造全体を XML としてエクスポートします
• スマート待機: カスタムタイムアウト付きで要素の出現を待機します
• スクロール検出: 長いリスト内の要素を見つけるために自動スクロールします

高度な機能

• トースト検出: 検証用にシステムのトーストメッセージをキャプチャします
• アクティビティの監視: 特定の Android アクティビティを待機します
• バックグラウンド操作: 時間のかかる操作に対する非同期対応

ユースケース

以下に最適です。

• 実デバイスと対話する必要がある AI エージェント
• リモートデバイス制御のセットアップ
• 自動化された QA ツール
• Android ボットフレームワーク
• UI テストと自動化
• デバイス管理と監視

インストール

1. リポジトリをクローンする

git clone https://github.com/nim444/mcp-android.git
cd mcp-android

2. 仮想環境を作成して有効化する

# Using uv (https://github.com/astral-sh/uv)
uv venv
source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate

3. 依存関係をインストールする

uv pip install

サーバーの実行

サーバーは用途に応じて 2 つの異なるトランスポートモードをサポートしています。

オプション 1: MCP stdio（AI エージェント連携用）

これは Claude Desktop、VS Code、その他の MCP クライアントなどの AI エージェントと連携するための標準モードです。

# Edit server.py to use stdio mode (default commented out)
# Uncomment the stdio section and comment out http section

# Then run:
uv run python server.py

オプション 2: Streamable HTTP（Web/API 連携用）

このモードではサーバーを HTTP API として実行します。Web アプリケーション、curl でのテスト、直接の HTTP 呼び出しに便利です。

# Current default configuration - runs as HTTP server
uv run python server.py

# Server will be available at: http://localhost:8080

モードの切り替え

server.py を編集し、if __name__ == "__main__": セクションを変更します。

stdio モード（AI エージェント）の場合:

if __name__ == "__main__":
    mcp.run(
        transport="stdio",
        show_banner=False,
    )

HTTP モード（Web API）の場合:

if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",
        host="0.0.0.0",
        port=8080,
    )

使用方法

AI エージェント連携の場合（Claude Desktop、VS Code など）

このサーバーを使用するには MCP クライアントが必要です。Claude Desktop アプリは MCP クライアントの一例です。

重要: AI エージェント連携では、サーバーを stdio モード（上記の「オプション 1」を参照）で設定してください。

Claude Desktop でこのサーバーを使用するには:

Claude Desktop の設定ファイルを特定する

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

mcpServers セクションに Android MCP サーバーの設定を追加する

{
  "mcpServers": {
    "mcp-android": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "cd /path/to/mcp-adb && source .venv/bin/activate && uv run python server.py"
      ]
    }
  }
}

/path/to/mcp-adb を、このリポジトリをクローンした絶対パスに置き換えてください。例: /Users/username/Projects/mcp-adb

VS Code での使用

この MCP サーバーは VS Code のエージェントモードでも使用できます（VS Code 1.99 以降が必要です）。設定するには:

1. ワークスペースに .vscode/mcp.json ファイルを作成します:

{
  "servers": {
    "mcp-android": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "cd /path/to/mcp-adb && source .venv/bin/activate && uv run python server.py"
      ]
    }
  }
}

/path/to/mcp-adb を、このリポジトリをクローンした絶対パスに置き換えてください。

設定を追加したら、次の方法でサーバーを管理できます:

• コマンドパレット → MCP: List Servers で設定済みのサーバーを表示および管理
• コマンドパレット → MCP: Start Server でサーバーを起動
• サーバーのツールは VS Code のエージェントモードチャットで利用可能になります

HTTP API 連携の場合（直接 API 呼び出し）

HTTP モード（オプション 2）で実行している場合、HTTP リクエストを介してサーバーと直接やり取りできます:

# Check if server is running
curl http://localhost:8080/

# List available tools (you'll need to implement proper tool discovery endpoints)
# This depends on your FastMCP version and configuration

HTTP モードのユースケース:

• Android 自動化を伴う Web アプリケーション
• stdio を使用できないテストツール
• 他のサービスとの直接の API 連携
• curl/Postman を使用したデバッグと開発

UI インスペクター

このプロジェクトは、デバイスのインターフェース構造を表示および分析するための強力な UI インスペクションツールである uiauto.dev をサポートしています。

1. UI インスペクターをインストールします:

uv pip install uiautodev

2. インスペクターを起動します:

uiauto.dev

3. ブラウザーを開き、https://uiauto.dev にアクセスします

利用可能な MCP ツール

デバイス管理ツール

ツール名	説明
mcp_health	MCP サーバーが正常に動作しているかを確認します
get_device_status	デバイスの完全なステータスと準備状況の情報を取得します
connect_device	Android デバイスに接続し、基本情報を取得します
get_device_info	シリアル、解像度、バッテリーなどの詳細なデバイス情報を取得します
check_adb_and_list_devices	ADB がインストールされているかを確認し、接続されているデバイスを一覧表示します

アプリケーション管理ツール

ツール名	説明
get_installed_apps	インストールされているすべてのアプリをバージョンとパッケージ情報とともに一覧表示します
get_current_app	現在フォアグラウンドにあるアプリの情報を取得します
start_app	パッケージ名でアプリを起動します
stop_app	パッケージ名でアプリを停止します
stop_all_apps	現在実行中のすべてのアプリを停止します
clear_app_data	指定したアプリのユーザーデータ/キャッシュを消去します

画面制御ツール

ツール名	説明
screen_on	画面をオンにします
screen_off	画面をオフにします
unlock_screen	画面のロックを解除します（必要に応じてオンにしてスワイプします）
wait_for_screen_on	画面がオンになるまで非同期で待機します

ユーザー入力ツール

ツール名	説明
press_key	ハードウェアキーの押下をシミュレートします（例: home、back、menu など）
click	text、resourceId、または description で要素をタップします
long_click	要素を長押しします
send_text	現在フォーカスされているフィールドにテキストを入力します（オプションで入力前にクリアします）
swipe	ある座標から別の座標へスワイプします
drag	要素を画面上の特定の位置へドラッグします

検査ツール

ツール名	説明
get_element_info	UI 要素の情報（テキスト、境界、クリック可否など）を取得します
wait_for_element	要素が画面に表示されるまで待機します
scroll_to	指定した要素が表示されるまでスクロールします
screenshot	デバイスからスクリーンショットを取得して保存します
dump_hierarchy	現在の画面の UI 階層を XML としてダンプします

高度なツール

ツール名	説明
get_toast	画面に最後に表示されたトーストメッセージを取得します
wait_activity	特定のアクティビティが表示されるまで待機します

---

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています - 詳細は LICENSE ファイルをご覧ください。