Appium MCP Claude Android

🚀 MCP Appium - モデルコンテキストプロトコルを用いたモバイル自動テスト

MCP Appiumは、AppiumをMCP（モデルコンテキストプロトコル）サーバーとして提供することで、AIエージェントがモバイルデバイスを自動的に制御し、テストを実行することを可能にします。

✨ 主な機能

• 自動サーバー起動: Appiumサーバーを自動で起動します（GUI不要）。
• 自動デバイス検出: adb devices を利用して、接続されたAndroidデバイスを自動検出します。
• 自動設定: 検出したデバイス情報を基に設定ファイルを自動生成します。
• 柔軟なテスト: 特定のアプリに制限されず、デバイスのすべてのアプリを自由にテストできます。
• MCP統合: Claude CodeなどのAIエージェントと完全に統合されます。
• ワンクリックインストール: 自動インストールスクリプトを使って、簡単にインストールしMCPに登録できます。

🚀 クイックスタート

1. インストール

方法1: リポジトリをクローンしてインストール（推奨）

git clone https://github.com/supremehyo/appium-mcp-claude-android.git
cd appium-mcp-claude-android
./install.sh

方法2: リモートインストール（ホームディレクトリにインストールされます）

curl -sSL https://raw.githubusercontent.com/supremehyo/appium-mcp-claude-android/main/install-remote.sh | bash
# インストール後: cd ~/.mcp-appium

2. Claude Codeで開く

# インストールしたディレクトリで
claude
# または他の方法でClaude Codeを該当ディレクトリで実行

Claude Codeは .mcp.json を自動的に検出し、MCPサーバーの承認を要求します。

3. 使用方法

Claude Codeで:

"接続されているデバイスを確認してください"  → list_devices
"Appiumを設定して接続してください"  → setup_appium_connection (自動設定!)
"現在の画面要素を表示してください"  → get_screen_elements

詳細なインストール方法は INSTALL.md を参照してください。

📚 詳細ドキュメント

必須要件

1. Node.jsとAppiumのインストール

# Node.jsのインストール (https://nodejs.org/)

# Appiumをグローバルにインストール
npm install -g appium

# UiAutomator2ドライバーのインストール
appium driver install uiautomator2

2. Android SDKとADBのインストール

• Android Studioをインストールした後、SDK Platform-Toolsをインストールします。
• または、スタンドアロンのPlatform-Toolsをダウンロードします: https://developer.android.com/studio/releases/platform-tools

環境変数の設定:

# macOS/Linux (.bashrcまたは.zshrcに追加)
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools

# Windows (システム環境変数に追加)
ANDROID_HOME=C:\Users\YourName\AppData\Local\Android\Sdk
Path=%Path%;%ANDROID_HOME%\platform-tools

3. Pythonパッケージのインストール

pip install -r requirements.txt

デバイスの準備

Android実機

1. USBデバッギングを有効にする（開発者オプション）。
2. USBでコンピューターに接続する。
3. デバッギングの許可を承認する。
4. ターミナルで確認: adb devices

Androidエミュレーター

1. Android StudioのAVD Managerでエミュレーターを作成して起動する。
2. ターミナルで確認: adb devices

使用方法

注意: 上記の「クイックスタート」でインストールスクリプトを実行した場合、MCPサーバーはすでに登録されています。

インストールの確認

# MCPサーバーの一覧を確認
claude mcp list

# "appium" が一覧に含まれている必要があります

基本的なワークフロー

1. デバイス接続の確認

   list_devicesツールを使用
   

2. Appiumの自動設定と接続

   setup_appium_connectionツールを使用
   

   このツールは以下を自動的に実行します:

   • Appiumサーバーの起動
   • 接続されたデバイスの自動検出
   • 設定ファイルの自動生成
   • デバイスの接続

3. 画面要素の確認

   get_screen_elementsツールを使用
   

4. アクションの実行

   execute_actionツールでタップ、入力、スワイプなどを実行
   

5. 自動化シナリオの実行

   run_test_scenarioツールで自然言語のシナリオを実行
   

MCPツールの一覧

1. setup_appium_connection

Appiumサーバーを起動し、デバイスに自動的に接続します。

パラメータ:

• port (オプション): Appiumサーバーのポート (デフォルト: 4723)

例:

"Appiumを設定してデバイスに接続してください"

2. list_devices

接続されているすべてのAndroidデバイスの一覧を表示します。

例:

"接続されているデバイスの一覧を表示してください"

3. start_appium_server

Appiumサーバーのみを手動で起動します。

パラメータ:

• port (オプション): Appiumサーバーのポート (デフォルト: 4723)

4. stop_appium_server

実行中のAppiumサーバーを停止します。

5. get_screen_elements

現在の画面のすべてのUI要素を取得します。

6. execute_action

モバイルデバイスで特定のアクションを実行します。

サポートされるアクション:

• tap: 要素をタップする
• input_text: テキストを入力する
• swipe: スワイプする
• long_press: 長押しする
• back: 戻る
• hide_keyboard: キーボードを非表示にする
• scroll_down: 下にスクロールする
• scroll_up: 上にスクロールする

7. run_test_scenario

自然言語で記述されたテストシナリオを自動的に実行します。

例:

"設定アプリを開いてWi-Fiメニューに移動してください"
"カカオトークを開いて検索ボックスに 'テスト' を入力してください"

例示的な使用シナリオ

シナリオ1: 基本設定とテスト

User: "接続されているデバイスを確認してください"
Claude: [list_devicesを実行]

User: "Appiumを設定して接続してください"
Claude: [setup_appium_connectionを実行]

User: "現在の画面に何があるかを表示してください"
Claude: [get_screen_elementsを実行]

User: "設定アイコンを押してください"
Claude: [execute_action with tapを実行]

シナリオ2: 自動化テスト

User: "ギャラリーアプリを開いて最初の写真を選択し、次に共有ボタンを押してください"
Claude: [run_test_scenarioを実行]

トラブルシューティング

"Appium not found" エラー

# Appiumがインストールされているか確認
appium --version

# インストールされていない場合はインストールする
npm install -g appium
appium driver install uiautomator2

"No devices found" エラー

# ADBでデバイスの接続を確認
adb devices

# デバイスが表示されない場合:
# 1. USBデバッギングが有効になっていることを確認する
# 2. USBケーブルを再接続する
# 3. エミュレーターを再起動する

"Connection refused" エラー

• ファイアウォールの設定を確認します。
• ポート4723が使用中かどうかを確認: lsof -i :4723 (macOS/Linux)
• 他のポートを使用する: setup_appium_connection を呼び出す際に port パラメータを指定します。

ログの確認

Appiumサーバーのログは appium.log ファイルに保存されます。

📄 ライセンス

MIT License