Android MCP

Android MCP サーバー

Android オペレーティングシステムを自動化するための軽量な MCP（Model Context Protocol）サーバーです。このサーバーは Android デバイスを直接操作するツールを提供し、自動テスト、アプリの操作、デバイスの制御を可能にします。

機能

• デバイス制御：Android デバイスでタップ、長押し、スワイプ、ドラッグ、文字入力を実行します
• 状態管理：必要に応じて画面のスクリーンショットを含むデバイスの状態を取得します
• ナビゲーション：ハードウェアボタンを押したり、通知にアクセスしたりできます
• 自動化：タイミングを制御するための待機機能を提供します
• エミュレーターのサポート：実機と Android エミュレーターの両方で動作します

前提条件

• Python 3.13 以降
• uv パッケージマネージャー
• USB デバッグを有効にした Android デバイスまたはエミュレーター
• インストール済みでアクセス可能な ADB（Android Debug Bridge）

インストール

1. uv をインストールする（未インストールの場合）

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Alternative: using pip
pip install uv

2. プロジェクトをセットアップする

# Navigate to the android MCP directory
cd mcp/android

# Install dependencies
uv sync

# Activate the virtual environment (optional, uv run handles this automatically)
source .venv/bin/activate

3. インストールを確認する

# Test the server
uv run main.py --help

使用方法

サーバーの実行

実機の場合：

uv run main.py

Android エミュレーターの場合：

uv run main.py --emulator

デバイスのセットアップ

1. Android デバイスで開発者向けオプションを有効にします：

   • 設定 > デバイス情報に移動します
   • 「ビルド番号」を 7 回タップします

2. USB デバッグを有効にします：

   • 設定 > 開発者向けオプションに移動します
   • 「USB デバッグ」を有効にします

3. デバイスを接続し、ADB 接続を確認します：

   adb devices
   

MCP サーバーの設定

MCP クライアントの設定（Claude Desktop、Cline など）に次の設定を追加します：

{
  "mcpServers": {
    "android-mcp": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "cd /path/to/agent/mcp/android && source .venv/bin/activate && uv run main.py --emulator"
      ],
      "alwaysAllow": [
        "State-Tool",
        "Click-Tool",
        "Type-Tool",
        "Swipe-Tool"
      ]
    }
  }
}

注：設定内のパスは、実際のプロジェクトの場所に合わせて更新してください。

設定オプション

• 実機の場合：args から --emulator フラグを削除します
• 特定のデバイス：--device <device_id> を追加して、特定のデバイスを指定します
• alwaysAllow：特定のツールを事前に承認し、繰り返し表示される権限確認を回避します

利用可能なツール

ツール	説明	パラメーター
Click-Tool	指定した座標をタップします	x: int, y: int
State-Tool	必要に応じてスクリーンショットを含むデバイスの状態を取得します	use_vision: bool = false
Long-Click-Tool	指定した座標を長押しします	x: int, y: int, duration: int
Swipe-Tool	座標間をスワイプします	x1: int, y1: int, x2: int, y2: int
Type-Tool	指定した座標にテキストを入力します	text: str, x: int, y: int, clear: bool = false
Drag-Tool	座標間でドラッグ＆ドロップします	x1: int, y1: int, x2: int, y2: int
Press-Tool	ハードウェアボタンを押します	button: str
Notification-Tool	通知パネルにアクセスします	なし
Wait-Tool	指定した時間だけ待機します	duration: int

トラブルシューティング

よくある問題

1. デバイスが見つからない：

   • USB デバッグが有効になっていることを確認します
   • adb devices の出力を確認します
   • 別の USB ケーブルやポートを試します

2. アクセスが拒否される：

   • デバイスで USB デバッグの許可を承認します
   • adb devices でデバイスの認証状態を確認します

3. 接続がタイムアウトする：

   • ADB を再起動します：adb kill-server && adb start-server
   • デバイスを再接続します

4. Python バージョンの問題：

   • Python 3.13 以降がインストールされていることを確認します
   • 必要に応じて uv python install 3.13 を実行します

エミュレーターのセットアップ

Android エミュレーターを使用する場合：

1. Android エミュレーターを起動します（通常は emulator-5554 としてアクセスできます）
2. 接続を確認します：adb connect emulator-5554
3. サーバーの実行時に --emulator フラグを使用します

開発

プロジェクト構成

mcp/android/
├── README.md
├── pyproject.toml
├── main.py           # MCP server entry point
├── src/
│   ├── mobile/       # Device interaction logic
│   └── tree/         # UI tree parsing and state management
└── .venv/           # Virtual environment

依存関係

• mcp：Model Context Protocol フレームワーク
• uiautomator2：Android デバイスの自動化
• pillow：スクリーンショットの画像処理
• ipykernel：Jupyter カーネルのサポート