android-use

android-use

安全対策を内蔵し、AI エージェントが ADB 経由で Android スマートフォンを確認・操作できるようにします。

android-use は、Model Context Protocol（MCP）サーバーです。MCP 対応アプリ（Claude Desktop、Claude Code、Cursor、Hermes Agent など）から、実機の Android デバイスのスクリーンショット撮影、画面上の UI の読み取り、タップ、スワイプ、文字入力、キーの押下、アプリの起動を行えます。v0.3 以降はリモートコネクターとしても実行できるようになりました。Claude.ai、ChatGPT、Cursor、LibreChat、Open WebUI、LM Studio に貼り付けられる、プライベートな https://…/mcp URL を利用できます。

npx -y @ghostfacemodz/android-use          # local (stdio) MCP server
npx -y @ghostfacemodz/android-use setup    # guided setup as a remote connector (URL + key)

2 分で始める

コンピューターを使う場合（Windows、macOS、Linux）：

1. Node.js 18 以降 と adb をインストールします（winget install Google.PlatformTools · brew install android-platform-tools · sudo apt install adb）。
2. スマートフォンで 開発者向けオプション → USB デバッグ（またはワイヤレスデバッグ）を有効にし、接続して確認メッセージを承認します。（スマートフォンのセットアップ）
3. 次を実行します。

   npx -y @ghostfacemodz/android-use setup
   

   adb を確認してスマートフォンを検出します（必要に応じて adb pair / adb connect を実行できるよう案内します）。専用のシークレットトークンを作成してサーバーを起動し、無料の Cloudflare クイックトンネルを使って、公開用の https:// リンクを開くかどうかを尋ねます（cloudflared は自動でダウンロードされます）。その後、コネクター URL、キー、コピーして貼り付けられる設定が表示されます。
4. AI アプリに URL を貼り付けます（コネクターとして使う）。次回からは npx -y @ghostfacemodz/android-use start --tunnel を実行するだけです。

スマートフォンのみを使う場合（PC 不要、root 不要）： Termux をインストールし、コマンドを 1 つ実行します。docs/PHONE-ONLY.md をご覧ください。

Claude Desktop / Cursor 用のローカル MCP サーバーだけが必要ですか？ セットアップを省略して、MCP クライアントに追加するにある stdio 設定を使ってください。

以前の名称は android-adb-mcp です。ツール、環境変数、動作に変更はありません。変更されたのはパッケージ名、バイナリ名（android-use）、MCP サーバー名のみです。

⚠️ 大切なスマートフォンを接続する前に、安全性をお読みください。 このツールを使う AI は、画面をタップして行えることなら何でも実行できます。

Google、Android、Samsung とは提携、推奨、スポンサー関係にありません。「Android」は Google LLC の商標です。

---

目次

• できること
• このツールでできること
• スマートフォンをどの程度操作できるか
• 必要条件
• スマートフォンのセットアップ
• 2 分で始める
• コネクターとして使う（HTTPS 経由のリモート MCP）
• Termux を使ったスマートフォンのみのセットアップ（docs/PHONE-ONLY.md）
• MCP クライアントに追加する：Claude Desktop · Claude Code · Cursor · Hermes Agent · その他のクライアント
• 設定
• ツール
• 安全性
• リモートコンピューターで実行する（Tailscale + ADB）
• ユースケースと詳しい操作方法（docs/USE-CASES.md）
• 開発

できること

android-use は、adb コマンドラインツールを使う小さな TypeScript ラッパーです。stdio（デフォルト）または Streamable HTTP（--http、setup、start）経由で MCP クライアントと通信し、実行時依存関係は 2 つ（@modelcontextprotocol/sdk と zod）です。

例：「YouTube を開いて、lo-fi beats を検索して。」

1. current_app → com.sec.android.app.launcher
2. open_app { package: "com.google.android.youtube" }
3. ui_dump → #4 ImageView [clickable] desc="Search" center=980,140 …
4. tap_element { text: "Search" }
5. type_text { text: "lo-fi beats" }、続けて key_event { key: "enter" }
6. screenshot で結果を確認

できること

普段どおり AI アシスタントに話しかけてください。アシスタントが手順を判断し、android-use を使ってスマートフォン上で実行します。画面を確認し（ui_dump、screenshot）、操作し（open_app、tap_element、tap、swipe、type_text、key_event）、次に進む前に結果を確認します。スマートフォンのロックを解除しておく必要があります。

手順を追ったチュートリアル、より多くのプロンプト、各ユースケースの制限を含む完全なガイドは docs/USE-CASES.md にあります。

ハンズフリーでの用事

手が離せないときに、動画やストリームを再生したり、音楽をかけたり、ナビゲーションを開いたり、アラームやタイマーを設定したりできます。

実例： Tailscale と Wireless debugging 経由でスマートフォンに接続したアシスタントが、チャットメッセージだけで、持ち主がスマートフォンを操作できない間に YouTube チャンネルの最新動画を開き、その後別のチャンネルのライブストリームに切り替えました。

• 「Spotify で Discover Weekly のプレイリストを再生して、音量を少し上げて。」
• 「Google Maps を開いて、最寄りの Tesco までのルート案内を開始して。」
• 「12 分のタイマーを設定して。」

ヒント： アプリのパッケージ名がわからない場合は、list_apps を使うよう頼んでください。type_text は ASCII のみ対応しているため、アクセント記号や絵文字を含む検索語は入力できません。詳細 →

繰り返しのタップ操作

通知を消去したり、更新を確認したり、毎日の報酬の受け取りなど、同じ操作を毎日実行したりできます。スケジュールに沿って動作する AI エージェント（たとえば Claude Code をヘッドレスで実行する cron ジョブ）と組み合わせれば、毎朝実行できます。

• 「通知シェードを下に引き下げて、Clear をタップして。」 → 上端から swipe → tap_element "Clear" → key_event home
• 「[ゲーム]を開いて、毎日の報酬を受け取ってから、ホームに戻って。」 → open_app → screenshot → tap_element "Collect" → key_event home
• 「Galaxy Store を開いて、すべて更新して。」

制限： Google Play は購入が可能なため、デフォルトで機密性の高いアプリのリストに含まれています。そのため、Play 独自の自動更新を使用してください。スマートフォンがロックされていると、スケジュール実行は失敗します。各アプリの利用規約を遵守してください。 多くのゲームやアプリは自動化を禁止しており、アカウントが停止される場合があります。詳細 →

スマートフォンからのソーシャル投稿

アシスタントが実際のアプリを操作するため、サードパーティのスケジューラーを使わずに、TikTok のエディターや Instagram ストーリーズなど、モバイル限定の機能を利用できます。

• 「最新の写真から新しい Instagram ストーリーを作成して、確認できるようにシェアする直前で止めて。」
• 「最新の動画にこのキャプションを付けて TikTok にアップロードし、投稿画面のままにして。」
• 「最新の投稿についたコメントを読み上げて。」（ui_dump + swipe）

人間が確認できるようにしてください： 最終画面でアシスタントを停止させ、screenshot を送信するようにしてください。また、キャプションは自分で作成するか、承認してください。絵文字は入力できません。自動操作に関するプラットフォームのルールを遵守してください。「いいね」やフォローの大量実行、偽のエンゲージメントは禁止です。詳細 →

アクセシビリティ

タッチスクリーンの操作が難しい場合は、平易な言葉で AI に話しかけたり入力したりしてスマートフォンを操作し、ui_dump（画面上のテキスト）と screenshot（画像およびラベルのない項目）を使って画面の内容を読み上げてもらえます。

• 「今、画面には何が表示されていますか？」
• 「ダークモードをオンにして、文字を大きくしてください。」
• 「戻る」、「下にスクロール」、「音量を下げる。」（key_event back、swipe、key_event volume_down）

**現実的に考えてください：**これは TalkBack や Voice Access など、Android に組み込まれているツールを補完するものであり、置き換えるものではありません。これらのツールはスマートフォン上で動作し、オフラインでもロック画面でも使えます。android-use にはコンピューター、接続環境、AI サービス、ロック解除済みのスマートフォンが必要で、動作も遅くなります。詳細はこちら →

家族へのリモートサポート

Tailscale と ADB デバッグを使って、どこからでも家族の設定を修正できます。着信音を元に戻したり、文字を大きくしたり、見当たらないアプリのアイコンを探したりできます。ADB_SERIAL を家族のスマートフォンに設定すれば、ほかの端末には一切触れられません。

• 「母さんのスマートフォンの着信音が鳴らない。サウンドモードに戻して、着信音の音量を70%くらいにして。」
• 「父さんのフォントを1段階大きくして、太字をオンにして。」

**必ず本人の同意を得てください。**本人が「USB デバッグを許可しますか？」というプロンプトを承認するとアクセスが許可されます。また、USB／ワイヤレスデバッグをオフにするか、Tailscale を切断すれば、いつでもアクセスを無効にできます。機密性の高いアプリを保護する機能はオンのままにしてください。詳細はこちら →

スマートフォンで可能な操作の範囲

要するに、ロック解除済みの画面をタップしてできることは、ADB の制限と以下のガードの範囲内で、AI も実行できます。これは src/ のコードに基づいています。詳しい説明はこちらをご覧ください。

できること	できないこと	デフォルトで無効
画面を見る（screenshot）	ロック画面を突破する、または PIN を回避する	生の shell ツール（ALLOW_SHELL=1）
UI をテキストとして読み取る（ui_dump）	スマートフォンをルート化する、またはシステム権限を取得する	銀行、決済、メッセージ、パスワードの各アプリ（ALLOW_SENSITIVE=1）
タップ、長押し、スワイプ	アプリのプライベートデータ（チャット、データベース、保存済みログイン情報）を読み取る	デバイスの許可リスト：ADB_SERIAL を設定するまで無効（推奨）
テキストを入力する（印字可能な ASCII のみ）	USB デバッグとワイヤレスデバッグの両方がオフの状態で操作する
キーを押す（ホーム、戻る、最近使ったアプリ、音量、電源、Enter など）	絵文字または非 ASCII テキストを入力する
アプリを開く、アプリ一覧を表示する、フォアグラウンドのアプリを見る	電話の通話を聞く、または話す

**できないことの詳細：**画面を点灯させることはできますが、PIN、パターン、パスワードなしでロックを解除することはできません。ADB は Android の権限が制限された shell ユーザーとして動作するため、スマートフォンをルート化したり、他のアプリのプライベートストレージを読み取ったりすることはできません。画面に表示されている内容だけを確認できます。また、アプリがセキュアとして設定した画面は黒く表示されます。USB デバッグとワイヤレスデバッグがオフの場合、またはスマートフォンがコンピューターを認証していない場合は、何も動作しません。

コードに実装されている安全ガード：

• デバイスの許可リスト：ADB_SERIAL（デフォルト：未設定のため、接続されているデバイスはすべて対象）。シリアル番号をカンマ区切りで指定します。それ以外のデバイスはすべて拒否され、list_devices にも表示されません。デフォルトでは最初の項目が使われます。
• **機密アプリのガード：ALLOW_SENSITIVE=1 を設定しない限り有効です。**機密アプリがフォアグラウンドにある間は、screenshot、ui_dump、tap、tap_element、swipe、long_press、type_text およびほとんどのキー操作が拒否され、open_app で起動することもできません。デフォルトでブロックされるアプリ：Google Wallet、Samsung Wallet/Pay、PayPal、Venmo、Cash App、Zelle、Coinbase、WhatsApp、Telegram、Signal、Google Messages、Samsung Messages、Messenger、Google Play。また、名前に bank、wallet、pay、finance、crypto、authenticator、messag、signal、keepass、bitwarden、1password のいずれかを含むパッケージも対象です。SENSITIVE_PACKAGES で追加できます。ホーム、戻る、最近使ったアプリ、電源は常に動作します。パッケージ名で判定するベストエフォートのヒューリスティックであるため、多くの銀行アプリは手動で追加する必要があります。
• 生のシェルはデフォルトで無効：ALLOW_SHELL。1 に設定しない限り、shell ツールは登録されません。有効にした場合、このツールには機密アプリのガードが適用されません。
• レート制限：RATE_LIMIT_PER_MIN（デフォルトは、ローリング方式で 1 分あたり 120 回の呼び出し）。
• **操作ログ：**すべてのツール呼び出しは、タイムスタンプと引数とともに標準エラー出力に記録されます。入力したテキストは文字数のみ記録されます。

アクセスをすぐに取り消す：スマートフォンでワイヤレスデバッグまたはUSB デバッグをオフにするか、ケーブルを抜いてください。完全にリセットするには、開発者向けオプション → USB デバッグの許可を取り消すを選択する、Tailscale を切断する、またはスマートフォンを再起動してください（adb tcpip セッションが終了します）。

推奨される安全な設定：

1. ADB_SERIAL に自分のスマートフォンだけを指定します。
2. ALLOW_SENSITIVE と ALLOW_SHELL は未設定のままにします。
3. 銀行アプリの名前にキーワードが含まれていない場合は、SENSITIVE_PACKAGES に追加します。
4. 画面ロックを有効にし、エージェントの作業中は画面を確認してください。
5. 公開または有料の操作を行う前に、アシスタントに停止するよう指示してください。
6. 作業が終わったらワイヤレスデバッグをオフにしてください。

要件

• Node.js 18 以降（npx を提供します）
• ADB（Android platform-tools）が PATH に設定されていること、または ADB_PATH を設定していること
  • macOS：brew install --cask android-platform-tools
  • Windows：winget install Google.PlatformTools を実行するか、platform-tools をダウンロードしてフォルダーを PATH に追加します
  • Linux：sudo apt install adb を実行します（または platform-tools の zip を使用します）
  • adb version で確認します
• USB デバッグまたはワイヤレスデバッグを有効にした Android スマートフォン（下記を参照）

スマートフォンの設定

1. 開発者向けオプションを有効にします： 設定 → デバイス情報（Samsung の場合：→ ソフトウェア情報）→ ビルド番号を 7 回タップします。
2. デバッグを有効にします： 設定 → 開発者向けオプション → USB デバッグやワイヤレスデバッグ（Android 11 以降）をオンにします。
3. Samsung： タップが無視される場合は、ADB の使用中に自動ブロッカー（設定 → セキュリティとプライバシー）をオフにします。Xiaomi および一部の他の ROM： **USB デバッグ（セキュリティ設定）**も有効にします。

USB で接続する： スマートフォンを接続し、「USB デバッグを許可しますか？」というプロンプトを承認してから、adb devices を実行します。

ワイヤレスで接続する（Android 11 以降）： 開発者向けオプション → ワイヤレスデバッグ → ペア設定コードによるデバイスのペア設定を選択します。この画面には、IP、ペア設定ポート、6 桁のコードが表示されます。メインのワイヤレスデバッグ画面には、別の接続ポートが表示されます。

adb pair 192.168.1.23:41234 123456     # pairing port + code
adb connect 192.168.1.23:37099         # connect port

アシスタントに connect_wifi { host, port, pairing_code, pair_port } を呼び出すよう依頼することもできます。

adb devices を実行して、デバイスのシリアル番号を控えてください。これを ADB_SERIAL に使用します。

コネクターとして使用する（HTTPS 経由のリモート MCP）

HTTP モードでは android-use は MCP のストリーム可能 HTTPトランスポートを使用するため、「URL で MCP サーバーを追加」できるアプリであれば、どのアプリからでもスマートフォンを使用できます。

エンドポイント	用途
POST/GET/DELETE /mcp	ストリーム可能 HTTP（現行の MCP 仕様。Mcp-Session-Id によるセッション）
GET /sse + POST /messages	旧バージョンのクライアント向けの従来の HTTP+SSE トランスポート
GET /health	稼働確認（認証なし。スマートフォンの情報は一切公開されません）

起動する

npx -y @ghostfacemodz/android-use setup             # guided: phone + token + optional public URL
npx -y @ghostfacemodz/android-use start --tunnel    # later: reuse saved phone + token, open a public URL
npx -y @ghostfacemodz/android-use start --funnel    # same, but a stable Tailscale Funnel URL
MCP_AUTH_TOKEN=... npx -y @ghostfacemodz/android-use --http --port 3333   # plain HTTP server, bring your own tunnel

setup はトークンを ~/.config/android-use/token（Windows では %APPDATA%\android-use\token）に所有者のみがアクセスできる権限で保存し、スマートフォンのシリアル番号を隣接する config.json に記録します。トークンは対話型ターミナルで実行した場合にのみ、コピー＆ペースト用の設定に表示されます（表示を抑制するには --hide-token、強制的に表示するには --show-token を指定します）。cat ~/.config/android-use/token を実行すると、いつでも再度確認できます。

公開 URL のオプション：

オプション	URL	備考
--tunnel（Cloudflare クイックトンネル）	https://<random>.trycloudflare.com/mcp	無料で、アカウントは不要です。cloudflared は自動的にダウンロードされます。URL は再起動するたびに変わるため、アプリに貼り直す必要があります。アウトバウンドポート 7844 が必要です（ネットワークによってはブロックされます）。
--funnel（Tailscale Funnel）	https://<machine>.<tailnet>.ts.net/mcp	固定です。 Tailscale と、tailnet で有効にした Funnel が必要です（有効になっていない場合、コマンドに管理者用リンクが表示されます）。
名前付き Cloudflare トンネル／独自のリバースプロキシ	独自のドメイン	固定です。http://127.0.0.1:3333 を転送先に指定します。

汎用リモート MCP 設定

{
  "mcpServers": {
    "android-use": {
      "url": "https://YOUR-HOST/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

カスタムヘッダーを送信できないアプリもあります。その場合は、代わりにトークンを URL に含めます：https://YOUR-HOST/mcp?key=YOUR_TOKEN。注意点： URL はヘッダーより漏えいしやすく（ブラウザーの履歴、スクリーンショット、プロキシやアプリのログ、共有チャットに残る可能性があります）、そのためヘッダーを使用できない場合に限り ?key= 形式を使用してください。共有は絶対にせず、漏えいした可能性がある場合はトークンをローテーションしてください（トークンファイルを削除して setup を再実行します）。android-use 自体がクエリ文字列をログに記録することはありません。X-API-Key: YOUR_TOKEN も使用できます。

アプリ固有のスニペット

Claude.ai と Claude Desktop（カスタムコネクター）： Settings → Connectors → Add custom connector → Remote MCP server URL：https://YOUR-HOST/mcp?key=YOUR_TOKEN（OAuth フィールドは空のままにします）。claude.ai で追加したカスタムコネクターは、Claude Desktop とモバイルにも表示されます。代わりに Claude Desktop でヘッダーを使用するには、claude_desktop_config.json で mcp-remote を介して接続します：

{
  "mcpServers": {
    "android-use": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://YOUR-HOST/mcp", "--header", "Authorization:${AUTH}"],
      "env": { "AUTH": "Bearer YOUR_TOKEN" }
    }
  }
}

Claude Code：

claude mcp add --transport http android-use https://YOUR-HOST/mcp --header "Authorization: Bearer YOUR_TOKEN"

Cursor（~/.cursor/mcp.json または .cursor/mcp.json）：

{
  "mcpServers": {
    "android-use": {
      "url": "https://YOUR-HOST/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

ChatGPT（開発者モード）： ウェブで、Settings → Apps → Advanced settings → Developer mode をオンにし、次に Create app を選択します（新しい UI：Plugins → + → Add custom MCP server）。サーバー URL：https://YOUR-HOST/mcp?key=YOUR_TOKEN、認証：No authentication（URL 内のキーが認証に使用されます）。開発者モードは Plus、Pro、Business、Enterprise、Edu の各プランで利用できます。

LibreChat（librechat.yaml）：

mcpServers:
  android-use:
    type: streamable-http
    url: https://YOUR-HOST/mcp
    headers:
      Authorization: "Bearer ${ANDROID_USE_TOKEN}"   # set ANDROID_USE_TOKEN in LibreChat's .env
    timeout: 120000

Open WebUI： Admin Settings（または Settings）→ External Tools → + → Type：MCP (Streamable HTTP)、URL：https://YOUR-HOST/mcp、Auth：Bearer、Key：YOUR_TOKEN。ネイティブのツール呼び出しに対応したモデルとのチャットで、このツールを有効にします。

LM Studio（Program → Install → mcp.json を編集）：

{
  "mcpServers": {
    "android-use": {
      "url": "https://YOUR-HOST/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

LM Studio が同じコンピューター上で動作している場合は、トンネルを使わずに http://127.0.0.1:3333/mcp に直接接続することもできます。

Venice： Venice 独自のチャットアプリは、まだカスタム MCP サーバーに対応していません（機能リクエストの一覧にはありますが、まだリリースされていません）。上記のアプリのいずれか（LibreChat、Open WebUI、LM Studio 対応クライアントなど）で、Venice API キーを OpenAI 互換プロバイダー（https://api.venice.ai/api/v1）として追加し、そこでコネクターを追加すれば、Venice のモデルを android-use で引き続き使用できます。

HTTP+SSE のみを使用する古いクライアント： https://YOUR-HOST/sse を使用します（Authorization ヘッダーを指定するか、/sse?key=YOUR_TOKEN を使用します）。注：Cloudflare の quick トンネルは GET イベントストリームをバッファーするため、従来の /sse は --tunnel 経由では動作しません。/mcp（デフォルトでは通常の JSON を返し、問題なく動作します）、Tailscale Funnel、または名前付きトンネルを使用してください。

Docker

イメージは、コンテナー内の 0.0.0.0:3333 で HTTP モードを実行します。コンテナー内の adb はネットワーク経由（Wireless debugging または adb tcpip）で電話に接続します。Linux では --device /dev/bus/usb を指定すると USB パススルーも使用できます。

docker build -t android-use .
docker run -d --name android-use -p 127.0.0.1:3333:3333 \
  -e MCP_AUTH_TOKEN="$(cat ~/.config/android-use/token)" \
  -e ADB_SERIAL=192.168.1.23:37099 \
  -v android-use-adb:/root/.android \
  android-use
docker exec -it android-use adb pair 192.168.1.23:41234 123456   # first time only
docker exec -it android-use adb connect 192.168.1.23:37099

/root/.android ボリュームにはコンテナーの adb キーが保存されるため、電話で再度承認を求められることはありません。公開 URL を使用するには、ポート 3333 の前にトンネルまたはリバースプロキシを配置してください。

起動状態を維持する

scripts/keepalive.sh（このリポジトリおよび $(npm root -g)/@ghostfacemodz/android-use/scripts/ の npm パッケージ内にあります）は、バックグラウンドで android-use start を実行し、終了した場合は再起動します（macOS/Linux/Termux）：

scripts/keepalive.sh start --tunnel     # or --funnel
scripts/keepalive.sh status             # running? + current public URL
scripts/keepalive.sh restart
scripts/keepalive.sh stop

ログは ~/.config/android-use/android-use.log に記録され、現在の URL は常に ~/.config/android-use/connection.json に保存されます（トークンがそこに書き込まれることはありません）。Windows では、開いたままにしておくターミナルで npx -y @ghostfacemodz/android-use start --tunnel を実行するか、タスク スケジューラ／NSSM で実行してください。

コネクターのセキュリティ

• トークンは必須です。 MCP_AUTH_TOKEN またはトークンファイルがないと HTTP モードは起動しません。ただし、MCP_ALLOW_NO_AUTH=1 を設定した場合は例外です（テスト目的で 127.0.0.1 を使う場合に限り妥当です）。setup で生成されるトークンは 256 ビットのランダム値です。
• トークンは一定時間で比較されます。失敗した試行はトークンを記録せずにログへ記録され、クライアントごとに 1 分あたり 10 回までに制限されます。また、ツール呼び出しの制限（RATE_LIMIT_PER_MIN）に加えて、クライアントごとにリクエスト数が制限されます（HTTP_RATE_LIMIT_PER_MIN）。
• デフォルトでは 127.0.0.1 にバインドされるため、接続できるのはトンネル経由、または同じマシン上のアプリのみです。
• ブラウザベースのクライアントが動作するよう、デフォルトではすべてのオリジンからの CORS を許可しています。認証には Cookie ではなくトークンを使用するため、安全です。必要に応じて MCP_CORS_ORIGINS で制限してください。
• セッションは 30 分間操作がないと期限切れになり、同時に保持できるセッションは最大 50 件です。
• URL とトークンを知っている人は、あなたのスマートフォンを操作できます（デバイスロック、シェルなし、機密アプリのブロックといったガードの範囲内）。絶対に共有しないでください。トークンファイルを削除して、再度 setup を実行すると更新できます。アクセスをすぐに遮断するには、サーバーを停止するか、ワイヤレスデバッグ／USB デバッグをオフにしてください。

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

すべてのクライアントで同じコマンドを実行します：npx -y @ghostfacemodz/android-use。ADB_SERIAL にスマートフォンのシリアル番号を設定するのは任意ですが、強くおすすめします。設定を編集した後は、クライアントを再起動してください。

Claude Desktop

claude_desktop_config.json を編集します（Settings → Developer → Edit Config）：

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

{
  "mcpServers": {
    "android-use": {
      "command": "npx",
      "args": ["-y", "@ghostfacemodz/android-use"],
      "env": {
        "ADB_SERIAL": "R5CT1234ABC"
      }
    }
  }
}

Claude Code

claude mcp add android-use -- npx -y @ghostfacemodz/android-use

デバイスの許可リストを設定する場合：

claude mcp add android-use --env ADB_SERIAL=R5CT1234ABC -- npx -y @ghostfacemodz/android-use

すべてのプロジェクトで利用できるようにするには、--scope user を追加してください。claude mcp list で確認できます。

Cursor

プロジェクト内に .cursor/mcp.json を作成するか、どこからでも利用できるように ~/.cursor/mcp.json を作成します：

{
  "mcpServers": {
    "android-use": {
      "command": "npx",
      "args": ["-y", "@ghostfacemodz/android-use"],
      "env": {
        "ADB_SERIAL": "R5CT1234ABC"
      }
    }
  }
}

Hermes Agent

~/.hermes/config.yaml の mcp_servers に追加します：

mcp_servers:
  android_use:
    command: "npx"
    args: ["-y", "@ghostfacemodz/android-use"]
    env:
      ADB_SERIAL: "R5CT1234ABC"
    timeout: 120          # per-tool-call timeout in seconds
    connect_timeout: 60

Hermes を再起動するか、MCP を再読み込みしてください。ツールは mcp_android_use_ プレフィックス付きで表示されます。例：mcp_android_use_screenshot。tools.include／tools.exclude などのその他のオプションについては、Hermes MCP のドキュメントを参照してください。

その他のクライアント（汎用 stdio）

stdio サーバーを起動できる MCP クライアントであれば利用できます：

フィールド	値
トランスポート	stdio
コマンド	npx
引数	-y、@ghostfacemodz/android-use
環境変数（任意）	ADB_SERIAL、ALLOW_SHELL、ALLOW_SENSITIVE、SENSITIVE_PACKAGES、RATE_LIMIT_PER_MIN、ADB_PATH

または、グローバルにインストールして android-use バイナリを直接使用します：

npm install -g @ghostfacemodz/android-use
android-use        # speaks MCP over stdin/stdout; logs go to stderr

Windows に関する注意： クライアントが npx を見つけられない場合は、"command": "cmd" と "args": ["/c", "npx", "-y", "@ghostfacemodz/android-use"] を使用してください。クライアントの PATH に adb がない場合は、たとえば C:\\platform-tools\\adb.exe のように ADB_PATH を設定してください。

設定

すべての設定は環境変数で行います。

変数	デフォルト	意味
ADB_SERIAL	(任意のデバイス)	adb devices で取得したデバイスのシリアル番号をカンマ区切りで指定する許可リストです。それ以外のデバイスはすべて拒否されます。推奨。
ALLOW_SHELL	オフ	1 にすると、生の shell ツールを登録します。
ALLOW_SENSITIVE	オフ	1 にすると、機密アプリの保護機能を無効にします。
SENSITIVE_PACKAGES		機密扱いにする追加のパッケージ名をカンマ区切りで指定します。
RATE_LIMIT_PER_MIN	120	1 分あたりのツール呼び出しの上限です。
ADB_PATH	adb	adb バイナリへのパスです。

HTTP／コネクターモード（--http、setup、start）：

変数／フラグ	デフォルト	意味
MCP_TRANSPORT=http ／ --http	stdio	/mcp で Streamable HTTP を提供します（さらに /health と旧式の /sse も提供します）。
PORT ／ --port	3333	リッスンするポートです。
HOST ／ --host	127.0.0.1	リッスンするアドレスです。Docker 内またはファイアウォールの背後でのみ 0.0.0.0 を使用してください。
MCP_AUTH_TOKEN		クライアントが送信する必要のあるトークンです。HTTP モードはトークンがないと起動を拒否します。
MCP_AUTH_TOKEN_FILE	<config dir>/token	トークンを格納するファイルです（setup がモード 600 で作成します）。設定ディレクトリ：~/.config/android-use（Linux/macOS/Termux）、%APPDATA%\android-use（Windows）、または ANDROID_USE_HOME。
MCP_ALLOW_NO_AUTH	オフ	1 にすると、トークンなしで HTTP を使用できます。ローカルでのテスト専用です。
MCP_CORS_ORIGINS	*	CORS で許可するブラウザーのオリジンをカンマ区切りで指定します。
MCP_TRUST_PROXY	オフ（トンネル使用時はオン）	クライアントごとのレート制限に CF-Connecting-IP ／ X-Forwarded-For を使用します。
HTTP_RATE_LIMIT_PER_MIN	600	クライアントごとの 1 分あたりの HTTP リクエスト数です（ログイン失敗は 10 回／分）。
MCP_ENABLE_SSE	オン	0 にすると、旧式の /sse と /messages エンドポイントを無効にします。
MCP_JSON_RESPONSE	オン	0 にすると、POST の応答をプレーン JSON ではなく SSE としてストリーミングします。
CLOUDFLARED_PATH	自動	PATH にあるものや自動ダウンロードしたものの代わりに、この cloudflared を使用します。

ツール

ツール	機能
list_devices	接続済みデバイス（許可リストでフィルタリング）
connect_wifi	adb pair（コードは任意）と adb connect host:port
screenshot	MCP 画像として返される PNG スクリーンショット
get_screen_size	画面解像度（wm size）
tap	x,y の位置をタップ
swipe	ms の間に x1,y1 → x2,y2 へスワイプ
long_press	x,y の位置を ms の間長押し
type_text	フォーカス中のフィールドに入力（印字可能な ASCII、安全に引用）
key_event	home、back、recents、enter、power、volume_up/down、delete、tab、…、または数値のキーコード
open_app	パッケージ名でアプリを起動
list_apps	インストール済みパッケージ（デフォルトではサードパーティ製。フィルターは任意）
current_app	フォアグラウンドのパッケージ
ui_dump	uiautomator dump を、中心座標付きのクリック可能／ラベル付き要素の簡潔なリストとして出力
tap_element	テキスト／content-desc または resource-id で要素を検索してタップ
shell	生の adb shell。ALLOW_SHELL=1 の場合にのみ登録されます

list_devices と connect_wifi を除くすべてのツールで、serial を任意で指定できます。

安全性

これにより、AI モデルがスマートフォンを遠隔操作できるようになります。 メッセージの送信、商品の購入、設定の変更、データの削除、画面上のあらゆる情報の閲覧が可能です。モデルは誤りを犯すことがあり、目にしたテキスト（ウェブページ、メール、通知からのプロンプトインジェクション）によって誘導される場合があります。

組み込みの保護機能：

• デバイスの許可リスト： ADB_SERIAL を設定すると、許可したデバイスのみを操作できます。それ以外のシリアル番号へのリクエストは拒否されます。
• 機密アプリの保護： 銀行、決済、ウォレット、メッセージ、パスワード管理アプリがフォアグラウンドにある場合、screenshot、ui_dump、tap、swipe、type_text およびほとんどのキー操作は拒否され、open_app でこれらのアプリを起動することも拒否されます。判定には、組み込みのパッケージリストとキーワード照合（bank、pay、wallet、messag、…）を使用します。これは可能な範囲でのヒューリスティックであり、セキュリティ境界ではありません。ホーム、戻る、最近使ったアプリ、電源の操作は常に可能なため、アシスタントは機密アプリから離れることができます。ALLOW_SENSITIVE=1 で無効にできます。
• デフォルトでは生のシェルを使用不可： shell ツールは、ALLOW_SHELL=1 の場合にのみ使用できます。それ以外のすべてのツールは入力を検証し、adb は execFile を使って呼び出されます。お使いのコンピューター上のシェルを経由することはありません。
• レート制限： デフォルトでは、1 分あたり 120 回のツール呼び出しが可能です（RATE_LIMIT_PER_MIN）。
• ログ記録： すべてのツール呼び出しが stderr（お使いの MCP クライアントのログ）に記録されます。入力したテキストは長さのみ記録されます。
• デフォルトではローカル： stdio モードでは、サーバーはネットワークポートを開きません。HTTP モードはオプトイン方式で、デフォルトでは 127.0.0.1 にバインドされ、トークンがない場合は起動を拒否します（コネクターのセキュリティを参照）。スクリーンショットと UI ダンプは、それを要求した MCP クライアントにのみ送信されます。クライアントがお使いのデータをクラウド LLM に送信する場合があるため、AI プロバイダーを通じてスクリーンショットがデバイスの外部に送信される可能性があるものとして扱ってください。

推奨事項：可能であれば予備またはテスト用のデバイスを使い、機密アプリをロックしたままにし、エージェントの動作中は画面を見守り、作業が終わったらワイヤレスデバッグをオフにしてください。

リモートコンピューターで実行する（Tailscale + ADB）

クラウドコンピューターまたは VPS で動作する AI エージェントは、そこで android-use を実行することでスマートフォンを操作できます。

1. スマートフォンとリモートコンピューターの両方に Tailscale をインストールし、同じ tailnet に参加させます。それぞれの側から、相手の Tailscale アドレスが見えることを確認してください。
2. Android では、ワイヤレスデバッグのペアリングは同じローカル Wi-Fi からしか行えないため、任意の PC から一度だけ USB でセットアップします。

   adb devices          # accept the prompt on the phone
   adb tcpip 5555
   

   その後、スマートフォンのケーブルを抜きます。
3. リモートコンピューターで接続します。

   adb connect <phone-tailscale-ip>:5555
   

   そして、スマートフォンを許可リストに登録してサーバーを起動します。

   ADB_SERIAL=<phone-tailscale-ip>:5555 npx -y @ghostfacemodz/android-use
   

4. Tailscale に接続した状態で、スマートフォンを Wi-Fi またはモバイルデータ通信に接続したままスリープさせないでください。スマートフォンを再起動すると TCP モードがオフになるため、再起動後は手順 2 を繰り返してください。

作業が終わったら、USB／ワイヤレスデバッグをオフにし、スマートフォンの Tailscale を切断してください。

オプション：Twilio による AI 音声通話（予定）

ステータス： 追加機能として予定されていますが、まだ実装されていません。

ADB では通話の開始、応答、終了が可能ですが、Android では root 権限がないと、アプリから SIM 通話中に発話したり、音声を聞いたりすることはできません。予定されている追加機能では、代わりに Twilio を使用します。アシスタントが発信と応答に使える Twilio 番号に加え、テキスト読み上げ、Twilio Media Streams を介したリアルタイムの音声テキスト変換、各通話の文字起こしと要約を提供します。

準備として、Twilio アカウントを作成し、音声通話に対応した番号を購入して（月額約 $1.15 に加えて分単位の通話料金がかかります）、Account SID、Auth Token、電話番号を秘密情報として管理してください（TWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKEN、TWILIO_NUMBER）。これらをコミットしないでください。通話は SIM ではなく Twilio 番号から発信されます。英国、米国、EU を含む多くの地域では、相手に AI と会話していること、または録音されていることを伝える必要があります。そのため、このブリッジは各通話の開始時にその旨を通知します。スパム、自動音声通話、なりすましには使用せず、Twilio Console で利用上限を設定してください。

開発

git clone https://github.com/GhostFaceModz/android-adb-mcp
cd android-adb-mcp
npm install
npm test             # builds, then runs stdio + HTTP/auth + setup tests against a mocked adb (no phone needed)
node dist/index.js   # run the server from source

公開済みパッケージを MCP Inspector でテストします。

npx @modelcontextprotocol/inspector npx -y @ghostfacemodz/android-use

ロードマップ

• scrcpy による画面のライブストリーミング
• 要素が見つかるまでスクロールするヘルパーと、要素の表示を待つヘルパー
• Unicode テキスト入力（ADB キーボード IME 経由）
• ツールごとの確認プロンプト（MCP エリシテーション）
• iOS はサポートされておらず、今後も対応予定はありません（ADB に相当するものがありません）

ライセンス

MIT。詳細は LICENSE を参照してください。