AI导哈

Android WiFi控制服务

通过MCP客户端远程控制USB连接的Android手机的WiFi、网络、OTP和UI功能，适用于自动化手机QA测试和远程访问场景。

  • by dogkeeper886
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 dogkeeper886/android-wifi-mcp

使用说明

安卓wifi mcp

驱动USB连接的Android手机 WiFi、网络、OTP和UI 从任何MCP客户端（本地）或从网络上的另一台机器。

一 主控程序 将连接到主机的电话转换为可编程设备的服务器。它在说话 adb 到一个选定的Android设备并暴露 32工具 通过流式HTTP——扫描/连接WiFi（包括802.1X企业），运行网络诊断，捕获短信/通知OTP，读/写设置，推/拉文件。指向Claude（或任何MCP客户端）并自动进行电话QA：加入专属门户网络，等待OTP，驱动页面，点击对话框。

它也服务于 将整个QA堆栈连接到远程机器 --只需一个命令，主机即可发布android wifi 加 设备浏览器 加 在设备UI上，因此笔记本电脑未连接到手机的测试人员仍然可以对其运行端到端流。

运作原理

一部手机连接到一台主机。这 安卓wifi 服务器在它旁边运行并进行对话 adb其他一切都是关于 谁能拿到这些工具 和 旁边还有什么.

  • 安卓wifi --核心服务器：仅限HTTP(可流式传输的HTTP)on :3000，一次选择一个设备（使用多设备选择），全部 adb 通过 execFile 因此凭据不能被shell注入。
  • 无内置身份验证 --两个HTTP端点都绑定 0.0.0.0；控制是 网络边界 (刻意为之).

两个想法使堆栈不仅仅是一个服务器——每个想法都有自己的下图： 一个刀具表面 （其他MCP服务器如何融入）和 端到端远程流 （远程机器如何驱动所有这些）。

图表源位于 docs/images/ (*.svg)--使用以下命令重新生成PNG make readme-diagram.

快速启动（本地，约30秒）

npm install && npm run build
make doctor          # preflight: node, adb, device, build
# plug in the phone · enable USB debugging · tap "Allow" on the RSA prompt
make serve           # android-wifi on http://localhost:3000  (GET /health, POST /mcp)

用Claude Code注册它——捆绑的垫片桥stdio↔ HTTP，因为Claude Code的HTTP客户端不能直接使用Streamable HTTP(#7):

claude mcp add --transport stdio android-wifi -- node bin/android-wifi-shim.mjs http://localhost:3000/mcp

现在问： “列出设备，扫描WiFi，连接到 <ssid>." 在没有root级别adb访问权限的Linux上，运行 make udev 一次。

需要 节点≥18， adb和a 安卓11+ 设备（ cmd wifi 接口）。浏览器工具附加到 铬金丝雀 在设备上——稳定的Chrome的DevTools套接字在许多OEM版本上被锁定。

工具

安卓wifi注册 31个原生工具除此之外 上游代理 生成 其他 MCP服务器作为stdio的孩子，并将他们的工具合并到一个列表中——这样客户端就可以单独连接到安卓wifi并获得wifi/设备 + 浏览器 + 在设备UI上一起：

组 工具
设备 device_list · device_select · device_info · device_event_log · device_screenshot · query_log
无线网络 wifi_scan · wifi_connect · wifi_disconnect · wifi_status · wifi_enable · wifi_disable · wifi_list_networks · wifi_forget
企业802.1X wifi_connect_enterprise · wifi_disconnect_enterprise · wifi_check_companion_app
网络诊断 network_ping · network_dns_lookup · network_check_internet · network_check_captive · network_interface_info
短信/OTP sms_read_recent · sms_wait_for_otp
通知OTP notifications_list_recent · notifications_wait_for_otp
设置和文件 device_settings_get · device_settings_put · device_settings_delete · device_push_file · device_pull_file
代理 proxy_restart

现代Android没有发货 curl/nslookup，因此网络检查读取 dumpsys connectivity 和 ping （专属门户网站判决， VALIDATED 状态、接口/路由信息）。冲突的上游工具名称以前缀开头 <upstream>__.

远程访问(make serve-all)

要驾驶 满的 从另一台机器堆叠，在电话所在的主机上提供服务——然后一个远程代理对一部电话运行端到端流：

make serve-all        # android-wifi :3000 (+ mobile-next proxied in), android-playwright :8931, + CDP bridge
make serve-all-stop   # tear it all down

远程客户端注册 二 HTTP端点--复制 .mcp.json.example 并替换主机IP。两者都使用Streamable HTTP，无代码桥接 mcp-remote (--allow-http 对于纯HTTP LAN URL是必需的）：

"android-wifi":       { "command": "npx", "args": ["-y","mcp-remote","http://<HOST_IP>:3000/mcp","--allow-http"] },
"android-playwright": { "command": "npx", "args": ["-y","mcp-remote","http://<HOST_IP>:8931/mcp","--allow-http"] }

mobilenext不是第三个端口。 这是网络上的单会话SSE(#102)，所以 serve-all 将其作为 安卓wifi上游的stdio --其 mobile_* 工具骑android wifi的多会话 :3000（对于单个客户端本地运行， .mcp.json 将这三个服务器注册为单独的stdio服务器。)

安全

捆绑包是 未经设计验证 --仅凭可达性就可以完全控制手机（WiFi、OTP、屏幕截图、浏览器、UI）。这是可以接受的 可信网络上的实验室QA工具将定制的身份验证连接到异构服务器上比网络隔离更划算。将主机保持在受信任的LAN上，打开 :3000/:8931 仅限于已知的源IP（或将其置于VPN/Tailscale之后），并且从不将端口暴露给公共互联网。

企业WiFi和通知OTP（配套应用程序）

cmd wifi 无法执行802.1X，shell用户无法读取大多数通知——因此 伴侣应用 (com.example.wifimcpcompanionKotlin）通过Android的原生API连接这些。构建并安装一次：

cd companion-app && ./gradlew assembleDebug
adb install app/build/outputs/apk/debug/app-debug.apk
# open the app once; for notification OTPs, tap "Grant Notification Access"

然后 wifi_connect_enterprise （PEAP/TTLS/TLS；WPA2或WPA3企业版，通过 securityType)以及 notifications_wait_for_otp 工作； wifi_check_companion_app 报告安装+授权状态。短信OTP(sms_*)不需要应用程序，但是 content://sms/inbox 在某些三星/OEM版本上被锁定——回到那里的通知捕获。

结构化日志记录（可选，Postgres）

集 DATABASE_URL 每个工具调用+设备事件都会被记录下来——包括W3C跟踪上下文、设备连接/分离事件的故障归因和秘密编辑。取消设置后，服务器将在没有Postgres的情况下原封不动地运行。

make up && make migrate     # Postgres in Docker + schema (tool_calls, device_events, sessions)
DATABASE_URL=postgres://mcp:mcp@localhost:5433/android_wifi_mcp npm start
make psql                   # inspect — or use the query_log tool

配置

环境 默认 目的
PORT / HOST 3000 / 0.0.0.0 服务器绑定
ADB_PATH adb adb二进制文件的路径
UPSTREAM_MCP -- 生成上游MCP服务器： name=command [args…] (;-分隔）或JSON数组
PLAYWRIGHT_HEADED — 1 剧作家明显地往上游跑（条纹 --headless)
DATABASE_URL -- 设置后启用Postgres日志记录
LOG_LEVEL / LOG_DEST info / stderr 皮诺测井

serve-all 港口(PORT, PW_PORT, CDP_PORT)可在 make 线。看 .env.example.

文档

发展

make build        # tsc → dist/
make test-unit    # fast unit tests
make test         # full suite
make readme-diagram   # re-render every diagram PNG from its SVG source
make help         # all targets

cicd/tests/ 拥有一个由YAML驱动的、设备感知的测试工具（烟雾、短信、通知、代理套件），可以在每次运行时快照和恢复WiFi状态。CI住在 .github/workflows/.

许可证

MIT。

相关 MCP