PhoneMcp - Android Phone Control via ADB

📱 PhoneMCP — AI にスマートフォンを操作させる

AI アシスタントが Android スマートフォンを直接操作 —— Skill と MCP の 2 通りの接続方式に対応

📺 完全版デモ動画 · 🎬 クイックスタートチュートリアル

---

🎬 デモ

自然言語で AI にスマートフォンの操作を頼めます —— アプリを開く、メッセージを送る、商品を検索するなど、ひと言で完了します。

▶️ 完全版デモ動画を見る | 31 秒でクイックスタート

---

💡 これは何ですか？

PhoneMCP は AI によるスマートフォン操作ツールです。ADB を介して、AI アシスタントがスマートフォンの画面を直接確認し、ボタンをクリックし、文字を入力し、アプリを開くことができます —— まるで本物のアシスタントがスマートフォンを操作してくれるように使えます。

異なる AI クライアントのエコシステムに合わせて、2 通りの接続方式を提供します。

方式	適した用途	設定が必要か
⭐ Skill モード（推奨）	CatPaw、Claude Code など、Skill に対応するクライアント	設定不要。ダウンロードして展開すればすぐに使えます
MCP モード	Claude Desktop、Cursor などの MCP クライアント	MCP サーバーのアドレス設定が必要です

🏗️ 仕組み

┌─────────────────────────────────────────────────────────┐
│                      你的电脑                            │
│                                                         │
│  ┌──────────────┐              ┌──────────────────┐    │
│  │  AI 助手      │  Skill/CLI  │   PhoneMCP       │    │
│  │              │ ──────────► │                  │    │
│  │ · CatPaw    │   或 MCP     │  截图 / 点击      │    │
│  │ · Claude    │              │  输入 / 滑动      │    │
│  │ · Cursor    │              │  启动App / ...    │    │
│  │ · ...       │              │                  │    │
│  └──────────────┘              └────────┬─────────┘    │
│                                         │ ADB          │
└─────────────────────────────────────────┼───────────────┘
                                          │
                                   USB / WiFi
                                          │
                                ┌─────────▼─────────┐
                                │   Android 手机     │
                                │                   │
                                │  📱 屏幕截图       │
                                │  👆 触控操作       │
                                │  ⌨️ 文本输入       │
                                │  📦 应用管理       │
                                └───────────────────┘

✨ 機能

• 📸 スクリーンショット — スマートフォンのリアルタイム画面を取得します
• 👆 タッチ操作 — クリック、ダブルクリック、スワイプ
• ⌨️ 入力 — テキスト入力（中国語に完全対応）、テキストのクリア
• 🏠 ボタン操作 — 戻る、ホーム、音量、電源などのシステムボタン
• 📱 アプリ — アプリの起動、インストール済みアプリの検索、現在のアプリの取得
• 🎯 UI 要素の認識 — 画面上の UI 要素一覧を取得し、インデックスやテキストで正確にクリックします（推奨）
• 🔍 OCR モード — WebView、ゲーム、Flutter などの場面に対応し、OCR によるテキスト認識が可能です
• 📡 複数デバイス — USB と WiFi の接続に対応し、複数のデバイスを同時に管理できます

🚀 クイックスタート

前提条件

1. Android スマートフォンを USB でコンピューターに接続します（または WiFi で接続します）
2. スマートフォンで USB デバッグを有効にします（手順は以下を参照）

💡 実行ファイルを使用する場合、ADB のインストールは不要です。ADB は内蔵されています。

📱 スマートフォンで USB デバッグを有効にする手順（クリックして展開）

手順 1：開発者向けオプションを有効にする

1. スマートフォンの 設定を開きます
2. デバイス情報に移動します（一部の機種では「設定 > システム > デバイス情報」）
3. ビルド番号を 7 回連続でタップし、「開発者モードになりました」というメッセージが表示されるまで続けます

💡 メーカーによって手順が多少異なる場合があります。

• 小米/Redmi：設定 → デバイス情報 → すべての仕様と情報 →「MIUI バージョン」を連続してタップ
• Huawei/Honor：設定 → デバイス情報 →「ビルド番号」を連続してタップ
• OPPO/realme：設定 → デバイス情報 →「ビルド番号」を連続してタップ
• vivo/iQOO：設定 → デバイス情報 →「ソフトウェアバージョン番号」を連続してタップ
• Samsung：設定 → デバイス情報 → ソフトウェア情報 →「ビルド番号」を連続してタップ
• OnePlus：設定 → デバイス情報 →「ビルド番号」を連続してタップ

手順 2：USB デバッグを有効にする

1. 設定のメイン画面に戻ります
2. システム → 開発者向けオプションに移動します（一部の機種では、設定一覧の下部に直接表示されます）
3. USB デバッグをオンにします
4. USB 経由でインストールと**USB デバッグ（セキュリティ設定）**がある場合は、それらもオンにします

手順 3：コンピューターに接続して許可する

1. USB ケーブルでスマートフォンをコンピューターに接続します
2. スマートフォンに「USB デバッグを許可しますか？」というダイアログが表示されます
3. 「このコンピューターからのデバッグを常に許可する」にチェックを入れます
4. OK／許可をタップします

⚠️ 注意事項：

• データ転送に対応した USB ケーブル（充電専用ではないもの）を使用してください
• 許可ダイアログが表示されない場合は、USB ケーブルを抜き差しするか、ターミナルで adb devices を実行して表示させてください
• 一部のスマートフォンでは、USB 接続モードで「ファイル転送 (MTP)」を選択する必要があります

---

⭐ 方法 1：Skill モード（推奨、設定不要）

最も簡単な方法：Skill の圧縮ファイルをダウンロードし、AI クライアントの Skill ディレクトリに展開すれば、すぐに使えます。

1. ダウンロード

Releases ページから、対応プラットフォームの Skill 圧縮ファイルをダウンロードします。

プラットフォーム	ダウンロードファイル
🍎 macOS (Apple Silicon)	phone-mcp-skill-macos-arm64.zip
🐧 Linux	phone-mcp-skill-linux-amd64.zip
🪟 Windows	phone-mcp-skill-windows-amd64.zip

2. Skill ディレクトリに展開

# CatPaw
unzip phone-mcp-skill-macos-arm64.zip -d ~/.catpaw/skills/phone-mcp/

# Claude Code
unzip phone-mcp-skill-macos-arm64.zip -d ~/.claude/skills/phone-mcp/

展開後のディレクトリ構成：

phone-mcp/
├── SKILL.md      # AI 操作指南（AI 自动读取）
└── phone-mcp     # 可执行文件（内嵌 ADB）

3. 使用開始

スマートフォンを接続したら、AI にそのまま話しかけます。

• 「微信を開いて、張三に『明日会おう』とメッセージを送って」
• 「画面を撮って、今のスマートフォンの画面を見せて」
• 「淘宝を開いて iPhone のスマートフォンケースを検索して」

AI は SKILL.md を自動的に読み込み、CLI 経由で実行ファイルを呼び出してスマートフォンを操作します。追加の設定は一切不要です。

CLI の使い方

Skill モードでは AI がこれらのコマンドを自動的に呼び出しますが、手動で使用することもできます。

# 检测连接的设备
./phone-mcp run '{"action":"list_devices"}'

# 截图
./phone-mcp run '{"action":"screenshot"}'

# 获取屏幕元素
./phone-mcp run '{"action":"get_ui_elements"}'

# 点击元素
./phone-mcp run '{"action":"tap_element","text":"微信"}'

# 输入文本
./phone-mcp run '{"action":"type_text","text":"你好"}'

# 批量执行
./phone-mcp run '[{"action":"launch_app","name":"微信"},{"action":"wait","seconds":2},{"action":"get_ui_elements"}]'

---

🔧 方法 2：MCP サーバーモード

Claude Desktop、Cursor など、MCP プロトコルに対応するクライアント向けです。まずサーバーを起動し、クライアントで接続を設定する必要があります。

ダウンロード

Releases ページから、単体の実行ファイルをダウンロードします。

プラットフォーム	ファイル
🐧 Linux	phone-mcp-linux-amd64
🪟 Windows	phone-mcp-windows-amd64.exe
🍎 macOS (Apple Silicon)	phone-mcp-macos-arm64

SSE モード（デフォルト、推奨）

# 启动服务器
./phone-mcp-macos-arm64 serve
# 默认监听 http://0.0.0.0:8009

MCP クライアントの設定に以下を追加します。

{
  "mcpServers": {
    "phone-mcp": {
      "url": "http://localhost:8009/Phone/sse"
    }
  }
}

STDIO モード

Claude Desktop など、実行ファイルを直接呼び出す場面に適しています。

{
  "mcpServers": {
    "phone-mcp": {
      "command": "/path/to/phone-mcp-macos-arm64",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

从源码运行

git clone https://github.com/kengerlwl/phoneMcp.git
cd phoneMcp
pip install -r requirements.txt
python main.py serve

命令行参数

phone-mcp serve [选项]

选项：
  -t, --transport TYPE   传输模式: sse 或 stdio（默认: sse）
  -H, --host HOST        监听地址（默认: 0.0.0.0）
  -p, --port PORT        监听端口（默认: 8009）
  --path PATH            MCP 路径（默认: /Phone）
  --guide                显示详细使用指南

---

🛠️ 支持的操作

操作	CLI action	MCP Tool	说明
列出设备	list_devices	list_devices	列出已连接的 Android 设备
连接设备	connect	connect_device	连接远程设备（WiFi/TCP）
断开设备	disconnect	disconnect_device	断开设备连接
截图	screenshot	get_screenshot	获取屏幕截图
获取元素	get_ui_elements	get_ui_elements	获取 UI 元素列表 ⭐
点击元素	tap_element	tap_element	通过索引/文本/ID 点击 ⭐
坐标点击	tap	—	点击指定坐标
双击	double_tap	—	双击指定坐标
滑动	swipe	swipe	滑动屏幕
输入文本	type_text	type_text	输入文本（支持中文）
清除文本	clear_text	clear_text	清除输入框文本
返回键	back	press_back	按返回键
主页键	home	press_home	按主页键
按键	key	press_key	发送任意按键事件
启动应用	launch_app	launch_app	通过名称或包名启动应用
当前应用	current_app	get_current_app	获取当前前台应用
搜索应用	search_apps	search_apps	搜索已安装应用
等待	wait	wait	等待指定时间

💡 推荐工作流：先调用 get_ui_elements 获取屏幕元素，再用 tap_element 精准点击，比直接使用坐标更可靠。

💬 使用示例

连接好手机后，你可以在 AI 助手中直接用自然语言操作手机：

• "帮我打开微信，给张三发一条消息说'明天见'"
• "截个屏看看手机现在的界面"
• "打开设置，把 WiFi 关掉"
• "打开淘宝搜索 iPhone 手机壳"
• "帮我看看手机上装了哪些应用"

AI 助手会自动调用 PhoneMCP 的工具来完成这些操作。

⭐ 支持项目

如果 PhoneMCP 对你有帮助，请给个 Star ⭐ 支持一下！

📄 License

MIT