ERIUS PHONE

erius-phone-mcp

ERIUS PHONE デバイスを、Claude Code、 Claude Desktop、Cursor、その他の MCP クライアントで使えるネイティブツールにする MCP サーバーです。ERIUS PHONE デバイスは、 エージェント専用の実機 Android スマートフォンまたはタブレットです。このサーバーを接続すると、 エージェントは次の操作を実行できます。

• デバイスを一覧表示する
• アクセシビリティツリーまたはスクリーンショットとして画面を読み取る
• タップ、長押し、入力、スワイプ、スクロールを行う
• アプリを起動・停止する、URL を開く、インテントを送信する
• APK をインストール・アンインストールする
• クラッシュログを取得する

エージェントがデバイスを直接操作します。連携用コードを書く必要はありません。

アーリーアクセス： このパッケージは 1.0 より前のバージョン（0.2.0）です。ツール名と 引数は、1.0 より前に変更される可能性があります。

必要条件

• Python 3.10+
• ERIUS PHONE のAPI キー。https://eriusphone.com で登録してください。詳細は 下記の「API キーの取得」を参照してください。

インストール

オプション A：uvx（インストール不要）。uv があれば、 MCP クライアントから uvx erius-phone-mcp でサーバーを起動できます。uv はパッケージを取得し、 専用の環境に保持します。以下のクライアント設定例では、この方法を使用しています。

オプション B：pip。他の Python プロジェクトと依存関係が競合しないよう、専用の仮想環境にインストールします。

python3 -m venv ~/.venvs/erius-phone-mcp
~/.venvs/erius-phone-mcp/bin/pip install erius-phone-mcp

これにより、~/.venvs/erius-phone-mcp/bin/erius-phone-mcp に erius-phone-mcp コマンドがインストールされます。クライアント設定の command には、この絶対パスを指定してください。Claude Desktop や Cursor などの GUI アプリからは、通常、仮想環境の PATH が見えないためです。python -m erius_phone_mcp でも、コマンドを実行した場合と同じ動作になります。

設定

サーバーは環境変数のみで設定します。

変数	必須	内容
ERIUS_PHONE_API_KEY	はい	ERIUS PHONE の API キーです。すべてのリクエストはこのキーで認証され、アカウントの範囲に限定されます。
ERIUS_PHONE_DEFAULT_DEVICE	いいえ	ツール呼び出しでデバイスが指定されていない場合に使用するデバイス ID（例：vanilla）です。設定しない場合、エージェントが各呼び出しで device を渡します。ID は list_devices で確認できます。
ERIUS_PHONE_API_URL	いいえ	API のベース URL です。既定値は https://api.eriusphone.com です。異なる URL を案内された場合のみ設定してください。
ERIUS_PHONE_TIMEOUT	いいえ	リクエストごとの HTTP タイムアウト（秒）です。既定値は 30 です。

API キーの取得

https://eriusphone.com からアクセスを申請してください。アーリーアクセス期間中は、ERIUS PHONE チームが各アカウントを手作業で設定します。API キーとデバイス ID は、チームから直接お送りします。登録後に連絡が届かない場合は、 [email protected] までメールでお問い合わせください。同じキーを使って、 https://eriusphone.com/dashboard/ のダッシュボードにログインできます。ダッシュボードではデバイスの稼働状況を確認できます。

キーはパスワードと同様に扱ってください。キーを持つ人は誰でもデバイスを操作できます。

重要： MCP クライアントはこのサーバーをサブプロセスとして起動しますが、 シェルで export した変数は通常、引き継がれません。以下の例のように、クライアントの env ブロックに 変数を設定してください。

MCP クライアントに追加する

どの例でも、キーとデバイス ID をご自身のものに置き換えてください。uvx ではなく pip でインストールした場合は、"command": "uvx", "args": ["erius-phone-mcp"] を "command": "/home/you/.venvs/erius-phone-mcp/bin/erius-phone-mcp" に置き換えてください。

Claude Code

claude mcp add erius-phone \
  -e ERIUS_PHONE_API_KEY=your-api-key \
  -e ERIUS_PHONE_DEFAULT_DEVICE=your-device-id \
  -- uvx erius-phone-mcp

-s user を追加すると、すべてのプロジェクトでサーバーを利用できるようになります。-s project を指定すると、共有の .mcp.json に書き込まれます。キーを共有の .mcp.json にコミットしないでください。Claude Code はこのファイル内の ${VAR} 参照を展開するため、代わりに環境変数にキーを保存できます。

{
  "mcpServers": {
    "erius-phone": {
      "command": "uvx",
      "args": ["erius-phone-mcp"],
      "env": {
        "ERIUS_PHONE_API_KEY": "${ERIUS_PHONE_API_KEY}",
        "ERIUS_PHONE_DEFAULT_DEVICE": "your-device-id"
      }
    }
  }
}

Claude Code 内で /mcp を実行し、erius-phone が接続されていることを確認してください。

Claude Desktop

claude_desktop_config.json を編集します（Settings → Developer → Edit Config）。macOS では ~/Library/Application Support/Claude/ に、Windows では %APPDATA%\Claude\ にあります。

{
  "mcpServers": {
    "erius-phone": {
      "command": "uvx",
      "args": ["erius-phone-mcp"],
      "env": {
        "ERIUS_PHONE_API_KEY": "your-api-key",
        "ERIUS_PHONE_DEFAULT_DEVICE": "your-device-id"
      }
    }
  }
}

Claude Desktop が uvx を見つけられない場合は、command に絶対パスを指定してください（which uvx）。編集後は Claude Desktop を完全に終了してから、再起動してください。

Cursor

すべてのプロジェクトで使う場合は、同じ mcpServers ブロックを ~/.cursor/mcp.json に、特定のプロジェクトで使う場合は .cursor/mcp.json に記述します。その後、Cursor Settings → MCP で erius-phone を有効にしてください。

その他の MCP クライアント

このサーバーは stdio 経由で MCP を使用します。クライアントで uvx erius-phone-mcp または erius-phone-mcp 実行ファイルを指定し、上記の環境変数を渡してください。

ツール

デバイスを操作する各ツールは、省略可能な device 引数を受け取ります。省略した場合、ツールは ERIUS_PHONE_DEFAULT_DEVICE を使用します。

アカウントとデバイス

ツール	説明
whoami	このサーバーが使用しているアカウントとキー、およびアクセス可能なデバイス ID を表示します。キーが機能するかどうかを手早く確認できます。
list_devices	キーでアクセスできるすべてのデバイスを、ライブ状態（起動状態、Android のバージョン、画面サイズ）とともに表示します。
get_device	デバイス 1 台の全ステータスを表示します。前面で現在実行中のアプリも含まれます。

画面の確認

ツール	説明
snapshot	現在の画面のアクセシビリティツリーのスナップショットです。表示されているすべての要素について、テキスト、役割、およびタップ／入力／スクロールに渡せる ref を表示します。ref はスナップショットごとにリセットされます。
screenshot	MCP の画像コンテンツとして画面を返すため、モデルが直接確認できます。デフォルトは JPEG、長辺 1024 px（数十 KB）です。format、quality、max_side、scale で変更できます。format="png", max_side=null を指定すると、フルサイズの PNG（スマートフォンでは約 3 MB）が返されます。テキスト行には画像と画面のサイズが表示されます。
foreground	前面にあるアプリ（パッケージ、アクティビティ）と、クラッシュダイアログが表示されているかどうかのみを返します。
wait_for_text	画面にテキストが表示されるまで待機します。待機時間は最大 timeout_ms（上限 120000）です。検出時のスナップショットを返します。

画面の操作

ツール	説明
tap	ref、表示されている text／content_desc、またはピクセル単位の x、y を指定してタップします。
long_press	ref、text／content_desc、または x、y を指定して長押しします（長押し時間 ms は省略可能）。
type_text	フィールドに入力します。最初に ref／text_target をタップしたり、フィールドを clear したり、入力後に Enter を押したりできます。
press_key	back、home、enter、delete、tab、escape、up、down、left、right、space、power、volup、voldown、recent、menu、wakeup、または数値のキーコードを押します。
swipe	デバイスのピクセル座標で、2 点間をスワイプします。
scroll	コンテナを上下左右にスクロールします。行の ref ではなく、ScrollView／List 自体の ref を渡してください。

アプリ

ツール	説明
launch_app	パッケージ名（例：com.android.settings）を指定して、インストール済みのアプリを起動します。
open_url	http／https／market の URL を開きます。特定のアプリを指定することもできます。
send_intent	任意のインテントアクション（例：android.settings.WIFI_SETTINGS）でアクティビティを開始します。データ、パッケージ、コンポーネント、追加情報も省略可能です。
stop_app	アプリを強制停止します。
list_apps	インストール済みのアプリを表示します。ユーザーがインストールしたアプリのみを表示するには、third_party_only=True を指定します。
install_apk	このサーバーを実行しているマシン上のファイルから APK をアップロードしてインストールします。パッケージ名、バージョン、インストールが成功したかどうかを返します。
uninstall_app	パッケージ名を指定してアプリをアンインストールします。
get_crash_log	デバイスのクラッシュログバッファ（logcat -b crash）を取得します。アプリのクラッシュ後に使用すると、実際のスタックトレースを確認できます。

クイック例

サーバーに接続したら、エージェントに通常の言葉で、たとえば 「ERIUS デバイスを一覧表示して、ホーム画面に移動し、連絡先を開いてください」 と依頼します。内部では次のように処理されます。以下の出力は実際のもので、一部を軽く省略しています。

1. デバイスを探します。 エージェントが list_devices を呼び出します。

{"devices": [
  {"id": "vanilla", "description": "redroid Android 13, no Google services", "state": "device",
   "bootCompleted": true, "android": "13", "sdk": 33, "screen": {"width": 720, "height": 1280}},
  {"id": "tablet1", "form": "tablet", "description": "redroid Android 13 (vanilla, tablet)", "state": "device",
   "bootCompleted": true, "android": "13", "sdk": 33, "screen": {"width": 1600, "height": 2560}}
]}

2. ホーム画面に戻り、画面を確認します。 press_key(key="home", device="vanilla") は {"ok": true} を返し、続いて snapshot(device="vanilla") は フォアグラウンドのアプリと、次のツリーを返します。

- Group
  - ScrollView [ref=1]
    - Group
      - AppWidgetHostView (Search)
        ...
      - Text [ref=4] "Gallery" (Gallery)
  - View (Home)
  - Group
    - Text [ref=5] "Contacts" (Contacts)
    - Text [ref=6] "WebView Browser Tester" (WebView Browser Tester)
    - Text [ref=7] "Camera" (Camera)

3. 項目をタップします。 tap(device="vanilla", ref="5")、tap(device="vanilla", text="Contacts")、tap(device="vanilla", x=102, y=1116) はいずれも連絡先を開き、 {"ok": true} を返します。アクションの後は必ず新しい snapshot を取得してください。 ref は次のスナップショットまでしか有効ではありません。

4. 結果を確認します。 foreground(device="vanilla") は 連絡先アプリを報告するようになり、screenshot(device="vanilla") はエージェントが直接確認できる画面画像を返します。

APK のインストールによる QA も同じ方法で行えます。

install_apk(device="vanilla", apk_path="/path/to/app.apk")
→ {"ok": true, "package": "com.erius.dashtest", "versionName": "1.0", "label": "ERIUS Dash Test",
   "adbOutput": "Performing Streamed Install\nSuccess", "ms": 94, ...}

ヒントと制限

• エラーはそのまま返されます。 API がアクションを拒否すると、ツール呼び出しは API のエラーコードとメッセージを伴って失敗します。たとえば、HTTP 404: SelectorNotFound ... nothing on screen matches {"text": "..."} や HTTP 422: no_launcher_activity のようになります。エージェントはメッセージを読み取り、対応を調整できます。
• 入力するにはフィールドが準備できている必要があります。 フィールドが開いている途中に送信したキー入力は失われます。フィールドをタップすると新しい画面が開く場合（Android の設定の検索など）は、タップしてから snapshot／wait_for_text で待ち、その後、対象を指定せずに type_text を呼び出してください。結果は snapshot で確認します。
• 入力できるのは ASCII のみです。 type_text がサポートするのは印字可能な ASCII のみです（adb の制限）。絵文字、アクセント付き文字、非ラテン文字は入力できません。
• コンテナーを指定してスクロールします。 scroll には、スクロール可能なコンテナーの ref が必要です（スナップショット内の ScrollView／List の行）。コンテナーに ref がない場合は、swipe を使用してください。
• スクリーンショットはコンテキストを消費します。 デフォルトのスクリーンショットは、長辺が 1024 px の JPEG です（数十 KB）。スマートフォンのフルサイズ PNG（1440×3120）は約 3 MB あり、多くの MCP クライアントが 1 回のツール結果として受け取れるサイズを超えます。snapshot（テキストで、はるかに小さい）を優先し、ピクセル情報が必要な場合にのみスクリーンショットを取得してください。
• 縮小されたスクリーンショット上の座標。 image_width と image_height（座標を読み取ったスクリーンショットのサイズ）を tap、long_press、swipe に渡さない限り、x と y はデバイスのピクセル単位です。
• install_apk はローカルファイルを読み込みます。 パスはスマートフォン上ではなく、erius-phone-mcp を実行しているマシン上のものです。APK はディスクから読み込まれ、呼び出しごとに全体がアップロードされます。
• サーバープロセス 1 つにつき API キーは 1 つです。 複数のアカウントを使用するには、異なる名前とキーで複数のサーバーエントリーを追加してください。
• レート制限。 API は IP ごとに毎秒約 30 リクエストを許可し、デバイスごとに最大 8 件のリクエストをキューに入れます。それを超えると HTTP 429 が返されます。

トラブルシューティング

• ERIUS_PHONE_API_KEY is not set：変数がサーバープロセスに渡されていません。シェルだけでなく、クライアントの env ブロックに設定してください。サーバーは起動時に stderr にもこの警告を出力し、クライアントの MCP ログに表示されます。
• no device id given and ERIUS_PHONE_DEFAULT_DEVICE is not set：ツール呼び出しで device= を渡すか、ERIUS_PHONE_DEFAULT_DEVICE を設定してください。list_devices で ID を確認できます。
• HTTP 401：キーが間違っているか、取り消されています。HTTP 403：デバイス ID が存在しないか、アカウントに登録されていません。whoami を実行すると、キーで使用できるデバイスを確認できます。
• HTTP 503 device_offline：デバイスが再起動中です。少し待ってから再試行してください。
• could not reach the ERIUS PHONE API at ...：URL が間違っているか、マシンから API に到達できません。ERIUS_PHONE_API_URL を確認し、接続が遅い場合は ERIUS_PHONE_TIMEOUT を大きくしてください。

ライセンス

MIT です。ライセンス全文は、パッケージに同梱されている LICENSE ファイルにあります。