Android Viewer

@acertijosapps/android-viewer

ブラウザーで Android エミュレーターをライブ表示するビューアーと、AI エージェントが操作できる MCP サーバーです。 Claude Code などの AI コーディングツールのブラウザーペイン向けに作られており、折りたたみ式端末の姿勢も含め、あなたとエージェントが同じエミュレーターをリアルタイムで表示し、操作できます。

• ライブ動画：WebSocket 経由の adb exec-out screenrecord（H.264）を、WebCodecs でブラウザー内でデコードします。
• 入力：クリック、ドラッグ、長押し、スクロールを adb shell input コマンドに変換します。
• マシン上のすべての AVD：実行中のエミュレーターを選ぶか、停止中のエミュレーターをビューアーから起動できます。
• エミュレーターのコントロール：戻る、ホーム、最近使ったアプリ、電源、音量、回転、フル解像度のスクリーンショット。
• 折りたたみ式端末：閉じる／半開き／開く／背面ディスプレイ。エミュレーターでは、エミュレーター標準のコントロールと同様にシミュレートされたヒンジを動かします。折りたたんだり回転したりすると、ストリームはアクティブなディスプレイに追従します。
• MCP サーバー：同じ操作をツールとして提供するため、エージェントのタップがビューアーにリアルタイムで表示されます。
• デバイスへのインストール不要：APK もサーバープッシュも不要で、必要なのは adb だけです。

要件

• Node.js 18 以降。
• Android SDK Platform-Tools（adb）。AVD の一覧表示と起動には emulator も必要です。 ANDROID_HOME、ANDROID_SDK_ROOT、またはデフォルトの SDK の場所から検出します。ADB と EMULATOR で上書きできます。
• WebCodecs に対応したブラウザー（Chromium ベースのブラウザー、Safari 16.4 以降、Firefox 130 以降）。
• macOS、Linux、Windows で動作します。

クイックスタート

npx @acertijosapps/android-viewer

http://localhost:8093 を開いてデバイスを選びます。ディープリンク：?avd=Pixel_10 または ?serial=emulator-5554。

android-viewer [options]        Start the viewer
android-viewer mcp [options]    Start the MCP server on stdio

  -p, --port <port>      Viewer port (default 8093, env PORT)
      --host <host>      Interface to bind (default 127.0.0.1, env HOST)
      --viewer-url <url> Viewer the MCP talks to (default http://localhost:8093)

その他の環境変数：MAX_DIM（エンコード動画の長辺。デフォルトは 1024）、BIT_RATE（デフォルトは 6M）、SCREENSHOT_MAX（MCP スクリーンショットの長辺。デフォルトは 1024）、DEBUG=1（すべての入力コマンドをログに記録）。

AI エージェントと使用する（MCP）

Claude Code：

claude mcp add android-viewer -- npx -y @acertijosapps/android-viewer mcp

その他の MCP クライアント：

{
  "mcpServers": {
    "android-viewer": {
      "command": "npx",
      "args": ["-y", "@acertijosapps/android-viewer", "mcp"]
    }
  }
}

公式 MCP Registry にも io.github.acertijosapps/android-viewer として掲載されています。

エージェントの操作を確認するには、ビューアーを起動したままにしてください（npx @acertijosapps/android-viewer）。ビューアーが起動していない場合、MCP は adb を通じてデバイスを直接操作します。

ツール	機能
list_devices	マシン上の AVD（実行中の場合は serial と booted を含む）とその他の adb デバイスを一覧表示します
launch_avd	名前を指定して AVD を起動します
get_state	ディスプレイサイズ、回転、現在の姿勢、利用可能な姿勢、ビューアーの URL を表示します
screenshot	アクティブなディスプレイの PNG。長辺は 1024 px 以下です
tap	input tap
swipe	input swipe。開始点と終了点が同じで 500 ms 以上の場合は長押しになります
press_key	back、home、recents、power、wakeup、volup、voldown、enter、delete、tab、escape
type_text	input text（印字可能な ASCII）
rotate	左または右に 90°回転します（エミュレーター）
set_posture	closed、half_opened、opened、rear_display、状態 ID、または reset を指定します。新しい状態を返します

座標はスクリーンショット全体に対して 0–1 に正規化されるため（x = pixel_x / image_width）、どの姿勢や向きでも使用できます。接続されているデバイスが 1 台だけの場合、serial は省略できます。

Claude Code のブラウザーペインで使用する

.claude/launch.json にビューアーを追加し、preview_start android-viewer で開きます。

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "android-viewer",
      "runtimeExecutable": "npx",
      "runtimeArgs": ["-y", "@acertijosapps/android-viewer"],
      "port": 8093,
      "autoPort": false
    }
  ]
}

HTTP API

MCP はビューアーの API を使用しており、同じ API を呼び出すこともできます。serial はクエリ文字列または本文に指定します。デバイスが 1 台の場合は省略できます。POST リクエストには content-type: application/json とローカルオリジンが必要なため、他のウェブサイトからデバイスを操作することはできません。

エンドポイント
GET /api/devices	[{ avd, serial, booted, model }]：serial: null = 停止中、booted: null = 時間内に応答なし
GET /api/state	ディスプレイサイズ、回転、displayId、姿勢、利用可能な姿勢
GET /api/screenshot?max=<px>	PNG。実際の画面サイズは X-Screen-Width / X-Screen-Height で確認できます
POST /api/tap	{ x, y }
POST /api/swipe	{ x1, y1, x2, y2, ms }
POST /api/key	{ key }
POST /api/text	{ text }
POST /api/posture	{ posture }
POST /api/rotate	{ direction: "left" | "right" }
POST /api/launch	{ avd }

ビューアーのタブがデバイスを表示している場合、操作はそのライブセッション経由で行われます。ビューアーはすぐに更新され、ジェスチャーによってフレームが生成されない場合はウォッチドッグがストリームを再起動します。

動作の仕組み

• デバイスごとに 1 つのセッションを作成し、すべてのタブで共有します。最後のタブが閉じると停止します。
• 1 秒ごとに dumpsys display（サイズ、回転、論理ディスプレイ 0 の背後にある物理ディスプレイ）と cmd device_state state を読み取ります。ディスプレイが変わると、状態が安定するまで待ってから、新しいパネルの --display-id を指定して screenrecord を再起動します。デバイスを折りたたむとパネルが切り替わります。
• screenrecord は画面が変化したときにのみフレームを出力するため、ビューアーは途中参加者向けに最後の IDR 以降の GOP を保持し、動画がない間はスクリーンショットを送信します。
• デバイスごとに実行する screenrecord は 1 つだけです。2 つ実行すると、エミュレーターのソフトウェアエンコーダーが枯渇します（err=-38）。クライアントからの再起動要求にはレート制限が適用されます。
• スクリーンショットには生の screencap を使用します（負荷が高いとき、エミュレーター内での PNG 圧縮は遅いためです）。面積平均で縮小し、ネイティブ依存関係なしで node:zlib を使って PNG にエンコードします。

制限事項

• ドラッグはリアルタイムではなく、指を離したときに送信されます（実際の継続時間を指定した input swipe を 1 回実行します）。
• キーボードのパススルーとオーディオにはまだ対応していません。type_text と press_key を使用してください。
• scrcpy などのネイティブクライアントより遅延が大きくなります。
• 複数のエミュレーターで同時に録画すると、ソフトウェアエンコーダーの動作が遅くなります。空き RAM が少ない場合（エミュレーターがスワップにページアウトされている場合）、adb shell の呼び出しごとに数秒かかることがあります。
• アプリが独自の姿勢を要求する場合（DeviceStateManager.requestState）、フォアグラウンドにある間は set_posture よりもその要求が優先されます。
• 物理ディスプレイが 1 つだけの Flip_Horizontal_Fold スタイルの AVD は、閉じると状態が変わりますが、表示される画像は変わりません。

ws-scrcpy を使わない理由

最初に ws-scrcpy を試しました。ストリーミングと入力は機能しますが、姿勢を変更すると、再読み込みするまで動画がフリーズします（scrcpy 1.19 のサーバーが以前のディスプレイにバインドされたままになるためです）。また、姿勢を制御する機能もありません。

貢献

ブランチモデル（main · beta）、Conventional Commits、リリースについては CONTRIBUTING.md に記載されています。変更内容は CHANGELOG.md に記載されています。

作者

AcertijosApps が作成しました。他のライブラリについては acertijosapps.com/librerias をご覧ください。

質問や提案：[email protected]、または issue を作成してください。

ライセンス

MIT