PhoneOnCloud MCP Server

讓 Claude Code、Claude Desktop、Codex、Cursor 或任何 MCP 工具直接操控你的雲端 Android 機器。

截圖與操控指令都是你的電腦與機器之間的 P2P WebRTC 直連，只有一開始建立連線的 握手會碰到 PhoneOnCloud 的伺服器。

1. 產生 token

1. 開 https://poc200.web.app 登入。
2. 在要操控的那台機器上，點 ⋯ 選單 → AI / MCP。
3. 填名稱（例如 MacBook — Claude Code）、選有效期限（預設 30 天）與要授予的權限。
4. 按 產生 token。

這串只會顯示一次，請立刻複製保存。遺失只能重新產生，救不回來。

Token 開頭是 poc_mcp_。把它當密碼看：在到期之前，它對你選的機器擁有你勾選的 全部權限。

2. 安裝

需要 Node.js 18 或更新的版本。

Claude Code

claude mcp add phoneoncloud -- npx -y @zerohuman-ai/poc-mcp --token poc_mcp_… --device <DEVICE_ID>

Claude Desktop

在 AI / MCP 面板下載 poc-mcp.mcpb（也可以到 最新 release 抓），雙擊 安裝。Claude Desktop 會跳出來問你的 token，並存進作業系統的 keychain。

Codex、Cursor 與其他吃 JSON 設定的工具

{
  "mcpServers": {
    "phoneoncloud": {
      "command": "npx",
      "args": ["-y", "@zerohuman-ai/poc-mcp", "--token", "poc_mcp_…", "--device", "<DEVICE_ID>"]
    }
  }
}

也可以用環境變數 POC_MCP_TOKEN 代替命令列參數——這樣 token 不會留在 shell 歷史，也不會被寫進可能被 commit 的設定檔。

3. 參數

每個參數都有 flag 與環境變數兩種寫法，flag 優先。

| Flag | 環境變數 | 預設 | 說明 | | :--- | :--- | :--- | :--- | | --token <TOKEN> | POC_MCP_TOKEN | — | 必填。 | | --device <ID> | POC_MCP_DEVICE_ID | — | 預設機器。token 只綁一台時可省略。 | | --profile <full\|core> | POC_MCP_PROFILE | full | core 只留截圖與操控相關的 12 個 tool。 | | --readonly | POC_MCP_READONLY | 關 | 隱藏所有會改動機器的 tool。 | | --unsafe-raw | POC_MCP_UNSAFE_RAW | 關 | 開放 send_raw_message。 | | --idle-timeout <秒> | POC_MCP_IDLE_TIMEOUT | 1800 | 這麼久沒有 tool 呼叫就斷線。0 = 永不主動斷。 | | --screenshot-max-edge <px> | POC_MCP_SCREENSHOT_MAX_EDGE | 1024 | 截圖長邊縮到這個大小。0 = 原生解析度。 | | --api-base <URL> | POC_MCP_API_BASE | 正式站 | 覆寫後端位址。 | | --inspector | POC_MCP_INSPECTOR | 關 | 開本機的 inspector 頁面，見下。 | | --inspector-port <PORT> | POC_MCP_INSPECTOR_PORT | 7333 | Inspector 的埠號，只綁 127.0.0.1。 |

如果覺得 AI 容易分心，可以試 --profile core：tool 清單短一點，模型挑對動作的 機率明顯較高。

Inspector

加 --inspector 會在 http://127.0.0.1:7333 開一個頁面，把 AI 收到的每一張截圖 連同它點的、拖的位置一起標出來，旁邊是它呼叫過什麼的即時紀錄。你也可以直接在那個 頁面自己操控機器。網址固定，可以加書籤。

預設關閉：一個 stdio server 悄悄佔一個埠很奇怪，而且同時開兩個 MCP 連線會互搶。 那個埠只聽 127.0.0.1，跨來源請求會被拒絕，寫入還要求一個其他網站設不出來的自訂 header。

4. Tool 清單

座標一律是 0–1000 的比例值，不是實際像素：(0,0) 是左上角、(1000,1000) 是右下角、 (500,500) 正中央。不論裝置解析度是多少、也不論截圖有沒有被縮小，這個對應都成立—— 所以沒有任何東西需要換算。x 與 y 各自獨立正規化，長螢幕上 100 單位的垂直距離 比 100 單位的水平距離長。

0.2.0 變更。 座標以前是實際像素。如果你的 prompt 或 CLAUDE.md 裡寫死了像素 座標，現在會被當成比例而點到錯的位置，請一併更新。

螢幕

| Tool | 功能 | | :--- | :--- | | screenshot | 目前畫面的 PNG，附帶像素尺寸。可選 crop、max_edge、quality。 | | get_screen_size | 機器螢幕的像素尺寸。僅供參考，算座標不需要它。 | | get_pixel_color | 單一像素的 RGB 與 hex。只想確認某一點有沒有變色時比截圖便宜。 | | review_last_screen_touch | 回傳 AI 上次碰螢幕時「牠當時看的那張截圖」，並在座標實際落點畫上十字（滑動的話連軌跡與終點一起畫），還會告訴牠那張圖跟那個動作之間隔了多久。動作沒生效時，這能直接回答「是座標算錯，還是畫面早就換了」，而且不用連線到機器。0.2.1 新增。 |

操控

| Tool | 功能 | | :--- | :--- | | tap | 點 x, y。給 hold_ms 就變長按。 | | swipe | 從一點拖到另一點。插值由機器端做，慢拖手勢不會被網路抖動打斷。 | | scroll | 滾輪事件。很多 Android App 不理它——清單捲動建議用 swipe。 | | input_text | 對已聚焦的欄位輸入文字。 | | press_key | 按鍵，可用名稱（BACK、HOME、ENTER、VOLUME_UP…）或原始 Android keycode。 | | navigate | back、home、recent。 | | rotate_screen | 切換橫豎向。螢幕尺寸會變，記得重新截圖。 | | wake_screen | 亮螢幕。 | | batch_input | 一次送最多 50 個操控動作，省 round trip。 |

檔案與 App

| Tool | 功能 | | :--- | :--- | | list_dir | 列目錄。路徑用絕對路徑，例如 /sdcard。 | | read_file | 讀檔。文字檔直接回文字；二進位回 base64 加上大小與 SHA-256。 | | write_file | 寫檔，會自動建上層目錄，大檔自動分塊。 | | rename_file | 改名或搬移。 | | delete_file | 刪除，無法復原。 | | install_apk | 安裝機器上已有的 APK，或先從你的電腦上傳。機器上已有同樣的內容就跳過上傳。 |

自動化與定位

| Tool | 功能 | | :--- | :--- | | run_script | 給 ES5 原始碼（content）直接在裝置上執行，並收集幾秒的輸出。 | | stop_script | 停掉正在跑的腳本。 | | set_location | 設定絕對的模擬 GPS 座標。 | | move_location | 以公尺或度數位移模擬座標。 |

診斷

| Tool | 功能 | | :--- | :--- | | list_devices | 這個 token 能用的機器，含狀態與螢幕尺寸。 | | get_connection_status | 連線狀態、RTT、閒置時間、token 到期日。 | | get_logs | 最近的腳本輸出、連線事件，以及每次 tool 呼叫一行的紀錄。 |

5. 要知道的幾件事

第一次 tool 呼叫可能要 40 秒。 建立連線會順便啟動機器的螢幕擷取管線，之後就 很快。如果那台機器已經有瀏覽器連著，連線會很快完成。

連著就等於機器在忙。 只要 MCP session 開著，機器就會一直跑螢幕擷取的編碼器 ——即使 MCP 從不要求視訊，因為觸控指令走的是同一條管線。閒置 30 分鐘會自動斷， 下次呼叫再自動連回來。

自動化腳本跑在 Otto，是 ES5 引擎，不是 Node。箭頭函式、模板字串、Promise、 async/await、Map、Set、展開運算子、解構全部不能用，會直接 parse 失敗。 請用 var、function () {}、字串相加。

撤銷 token 在下一次建立連線時才生效。 已經建好的 P2P DataChannel 不會因為 撤銷而中斷。要立刻切斷就把 AI 工具關掉。

6. 疑難排解

先看 get_connection_status，再看 get_logs。

| 訊息 | 意思與處理 | | :--- | :--- | | [token_expired] Your PhoneOnCloud MCP token expired on … | 到 AI / MCP 面板重新產生一個，並更新設定檔。 | | [token_revoked] This token was revoked. | 已被撤銷，請重新產生。 | | [token_invalid] Malformed token. | 複製時被截斷了。必須以 poc_mcp_ 開頭、中間有兩個點。 | | [device_not_running] Device … is stop. | 先到 dashboard 把機器開起來。 | | [scope_denied] This token does not allow … operations. | 產生 token 時沒勾這個權限，重新產生一個並勾上。 | | [device_not_found] Device … does not exist or is not yours. | deviceId 錯了，或 token 綁的是別台。跑 list_devices 確認。 | | [network] Cannot reach the PhoneOnCloud backend | 沒網路，或 proxy 擋了 *.cloudfunctions.net。 | | Handshake-ready timeout … scrcpy is still starting | 機器接受連線了但擷取管線還在啟動。過幾秒重試。 | | could not establish a peer-to-peer connection | 網路環境太嚴（公司 VPN、嚴格防火牆）擋掉了 WebRTC。 | | Multiple devices are available; pass device_id explicitly. | 設 --device，或每次呼叫都帶 device_id。 | | Another client kept winning the connection handshake | 有瀏覽器分頁在反覆連同一台機器。關掉它再試。 |

要看 server 自己在做什麼就看 stderr，MCP 工具通常會把它寫進自己的 log。 stdout 只走 JSON-RPC，不會有別的東西。

7. 安全性

• Token 在到期前，對你選的機器擁有你勾選的全部權限。AI 用不到的話， 執行自動化腳本、安裝 App、讀寫檔案這三個請取消勾選——這三個加起來 等於機器的完整控制權。
• 只想讓 AI 看、不要它動手，就加 --readonly。
• Token 會存在你的 MCP 工具放設定的地方。Claude Desktop 用 OS keychain； 其他工具可能是專案裡的一個明文檔案。建議用環境變數 POC_MCP_TOKEN， 不要把值寫進會被 commit 的檔案。
• 不用的 token 請到 AI / MCP 面板撤銷。

8. 專案位置

發佈與問題回報：https://github.com/zerohuman-ai/poc-mcp

英文版說明見 English。