Android Wifi MCP

安卓wifi mcp

MCP服务器，用于通过ADB（Android调试桥）在Android设备上进行WiFi控制。

此服务器使Claude和其他MCP客户端能够远程控制通过USB连接的Android设备上的WiFi连接。

特性

• WiFi控制：扫描、连接、断开连接、启用/禁用WiFi
• 网络类型：开放、OWE、WPA2-PSK、WPA3-SAE支持
• 802.1X企业WiFi：EAP-PEAP、EAP-TTLS、EAP-TLS支持（需要配套应用程序）
• 多设备：管理多个连接的Android设备
• 网络诊断：Ping、DNS查找、互联网连接、专属门户检测
• 设备信息：查询设备型号、Android版本和兼容性
• 设置和文件暂存：读/写 system/secure/global 设置，向设备推送文件/从设备拉取文件

何时使用此MCP与替代品

此服务器拥有 QA流的ADB级控制平面：WiFi、网络探测、OTP捕获、设备设置I/O、文件暂存。它故意这样做 不 发布通用的Android UI自动化或浏览器DOM工具——这些工具最好由您可以一起运行的上游项目提供。

这三个步骤组合得很干净：用Claude Code注册所有三个步骤，助手会编排适合每个步骤的内容。此服务器（#14）中的代理捆绑 @playwright/mcp 对于同一工具/列表中的主机端浏览器DOM，但移动mcp保持单独的注册。

对于gotcha on adb shell uiautomator dump （空根重试循环）--请参阅 docs/integrations/uiautomator-retry.md我们不提供UI转储工具；这是任何直接致电uiautomator的人的参考资料。

需求

主机PC

• Node.js 18+
• Android SDK平台工具（用于 adb)

- Fedora： sudo dnf install android-tools - Ubuntu/Debian： sudo apt install android-tools-adb - macOS： brew install android-platform-tools - Windows：从下载 Android开发者

安卓设备

• 安卓11（SDK 30）或更高版本
• USB调试已启用
• USB电缆连接到主机PC

用于企业WiFi或通知捕获（可选）

802.1X企业WiFi和捕获不通过短信到达的OTP（#3——WhatsApp/电子邮件/银行的通知监听器）需要配套的Android应用程序。如果您只需要WPA2/WPA3个人WiFi+基于短信的OTP，请跳过本节。

一次性主机设置（Linux示例，Fedora/RHEL）：

# JDK with javac (the headless variant alone won't compile)
sudo dnf install -y java-21-openjdk-devel

# Android command-line tools (~150 MB)
mkdir -p ~/Android/Sdk/cmdline-tools
curl -L -o /tmp/cmdline-tools.zip \
  "https://dl.google.com/android/repository/commandlinetools-linux-13114758_latest.zip"
unzip -q /tmp/cmdline-tools.zip -d /tmp && \
  mv /tmp/cmdline-tools ~/Android/Sdk/cmdline-tools/latest

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$PATH

yes | sdkmanager --licenses > /dev/null
sdkmanager "platforms;android-34" "build-tools;34.0.0" "platform-tools"

# Gradle 8.5 (only if you don't already have a system Gradle)
curl -L -o /tmp/gradle.zip "https://services.gradle.org/distributions/gradle-8.5-bin.zip"
unzip -q /tmp/gradle.zip -d /tmp && mv /tmp/gradle-8.5 ~/Android/gradle
export PATH=~/Android/gradle/bin:$PATH

在此之后， cd companion-app && gradle wrapper && ./gradlew assembleDebug 生产 app/build/outputs/apk/debug/app-debug.apk.

设置

1.在Android上启用USB调试

1. 首选 设置>关于手机
2. 轻按 版本号 7次启用开发人员选项
3. 首选 设置>开发人员选项
4. 启用 USB调试
5. 通过USB连接设备
6. 接受设备上的RSA密钥提示

2.验证ADB连接

adb devices

您应该看到您的设备被列为“设备”（而不是“未经授权”或“离线”）。

3.安装并运行MCP服务器

cd android-wifi-mcp
npm install
npm run build
npm start             # HTTP transport on http://localhost:3000
npm run stop          # Send SIGTERM to whatever is listening on $PORT (default 3000)
npm restart           # stop + start; use this after `npm run build` to pick up code changes

服务器说话 可流式传输的HTTP （MCP规范传输）。一个进程为所有连接的MCP客户端提供服务。

4.配置您的MCP客户端

Zed、Cursor和其他具有本机HTTP支持的MCP客户端

claude mcp add --transport http android-wifi http://localhost:3000/mcp

或者在JSON配置中：

{
  "mcpServers": {
    "android-wifi": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Claude Code（使用捆绑的stdio垫片）

Claude Code的捆绑HTTP MCP客户端在向Streamable HTTP服务器注册时崩溃（问题#7——错误在他们的二进制文件中，而不是我们的）。使用此包装附带的stdio垫片作为桥接件：

# After `npm install -g .` (or wherever the package is installed)
claude mcp add --transport stdio android-wifi android-wifi-shim http://localhost:3000/mcp

shim是一个~30-LOC节点CLI，它假装是Claude Code的stdio MCP服务器，并将每次调用转发到HTTP后端。没有Python或其他额外的依赖关系——与您已经拥有的Node工具链相同。

如果您没有全局安装：

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

5.设置企业WiFi（可选）

如果您只需要WPA2/WPA3个人网络，请跳过本节。

企业WiFi（802.1X/EAP）需要配套的Android应用程序，因为 cmd wifi 接口仅支持基于PSK的身份验证。

支持的EAP方法

构建和安装配套应用程序

1. 构建APK （需要Android SDK和Gradle）：

   cd companion-app
   gradle wrapper        # Generate wrapper (first time only)
   ./gradlew assembleDebug

1. 在设备上安装:

   adb install app/build/outputs/apk/debug/app-debug.apk

1. 启动应用程序 一次授予权限：

   adb shell am start -n com.example.wifimcpcompanion/.MainActivity

1. 验证安装:

   > Use wifi_check_companion_app to verify the app is installed

可用工具

32个原生工具 分为以下9类。使用可选 @playwright/mcp 上游启用（参见 代理上游MCP)，额外 **21 browser_* 工具 通过同一端点浮出水面 总计53**.

设备管理

设备设置（系统/安全/全局）

设备文件传输

WiFi控制

企业WiFi（802.1X）

网络诊断

短信/OTP

从以下位置读取短信 content://sms/inbox 通过adb shell——没有root，没有配套应用。 限制： 一些三星/OEM设备甚至限制短信内容提供商使用adb；这些工具返回一个空列表，其中包含 warning 这些设备上的字段，建议的回退是#3中计划的通知侦听器。

通知捕获（配套应用程序）

适用于不通过短信发送的OTP——WhatsApp、银行应用程序、电子邮件客户端等。配套应用程序的 NotificationListenerService 捕获整个系统的每个通知，然后主机MCP服务器通过用于企业WiFi的相同广播桥读取它们。 需要 用户授予 通知访问 通过设置访问配套应用程序一次→ 通知→ 通知访问（应用程序的主屏幕有一个一键快捷方式）。授予状态由以下人员报告 wifi_check_companion_app.

代理生命周期

代理（可选）

当 UPSTREAM_MCP 配置后，此服务器透明地公开来自同一命名空间中上游MCP服务器的工具。规范默认值(@playwright/mcp)添加21个DOM级别 browser_* 工具-- browser_navigate, browser_click, browser_fill_form, browser_evaluate, browser_snapshot, browser_take_screenshot等等。看 代理上游MCP 用于设置。这些驱动器 主机 铬今天；手机端Chrome在工作的Chrome DevTools协议路径上被屏蔽。

用法示例

列出已连接的设备

> Use device_list to see connected Android devices

连接到WiFi（WPA2/WPA3）

> Connect my phone to the network "HomeWiFi" with password "mypassword123"

这将使用 wifi_connect 与：

• ssid：“家庭WiFi”
• 安全性：“wpa2”
• 密码：“mypassword123”

连接到企业WiFi（802.1X）

> Connect to "CorpWiFi" using PEAP with username "user@corp.com" and password "secret"

这将使用 wifi_connect_enterprise 与：

• ssid：“CorpWiFi”
• eap方法：“peap”
• 身份：“user@corp.com"
• 密码：“secret”
• domainSuffixMatch：“radius.corp.com”（安卓11+系统需要）

检查连接状态

> What's the current WiFi status on my phone?

扫描网络

> Scan for available WiFi networks on my Android device

诊断连接性

> Check if my phone has internet access and detect any captive portal

读取或更改Android设置

> Read airplane_mode_on, then set private_dns_mode to "off"

用途 device_settings_get （命名空间 global，钥匙 airplane_mode_on)以及 device_settings_put （命名空间 global，钥匙 private_dns_mode，价值 "off").对于UI驱动的设置流（切换屏幕，而不是底层提供程序），请使用 mobile-next/mobile-mcp.

将证书推送到设备，然后安装

> Push /tmp/corp_ca.pem to /data/local/tmp/ca.pem, then install it as the CA cert "CorpCA"

链条 device_push_file 和 wifi_install_certificate.推动成功了 adb push；安装通过配套应用程序的网桥进行。

通过短信等待登录OTP

> Wait up to 60 seconds for an SMS OTP from "VERIFY" — give me the code as soon as it arrives

呼叫 sms_wait_for_otp 和 senderFilter: "VERIFY" 以及60秒的超时。当匹配的消息到达时，该工具返回提取的OTP字符串。在限制短信内容提供商的设备上（某些三星型号），请参阅#3了解通知侦听器回退。

参考

安全类型

环境变量

结构化日志记录（可选，阶段0b）

服务器可以记录对Postgres数据库的每次工具调用，以进行事后查询（问题#51）。这是 选择加入：set DATABASE_URL 并且记录层被激活；不设置它，服务器就会像以前一样运行。

# Bring up Postgres (Docker Compose) and apply migrations
make up
make migrate

# Run the server with logging enabled
DATABASE_URL=postgres://mcp:mcp@localhost:5433/android_wifi_mcp npm start

# Inspect rows
make psql
# > SELECT tool_name, surface, duration_ms FROM tool_calls ORDER BY started_at DESC LIMIT 10;

tool_calls 捕获每个调用的args/result/error duration_ms; device_events 和 sessions 是在后续阶段填充的占位符（内置观察器、会话路由）。模式存在于 migrations/.

敏感参数在INSERT之前被编辑。 中间件将这些键的值（不区分大小写）替换为 ***: password, privateKey, privateKeyPassword, caCertificate, clientCertificate, certificate。递归处理嵌套对象和数组。该列表位于 src/log/redact.ts --如果你引入了一个使用秘密方位arg的新工具，请添加它。

故障排除

“未连接任何设备”

1. 检查USB电缆连接
2. 验证USB调试是否已启用
3. 跑 adb devices 检查设备状态
4. 如果“未经授权”，接受设备上的提示

“连接了多个设备”

使用 device_select 选择要控制的设备：

> Select device with serial R5CT12345AB

“ADB不可用”

安装Android SDK平台工具并确保 adb 在您的路径中：

which adb  # Linux/macOS
where adb  # Windows

WiFi命令失败

• 确保安卓11+(cmd wifi 需要SDK 30+）
• 检查设备是否处于受限模式（工作配置文件等）
• 某些三星设备可能具有不同的行为

企业WiFi不工作

• 确保配套应用程序安装并启动一次
• 检查 wifi_check_companion_app 返回成功
• 验证RADIUS服务器的域后缀匹配是否正确

代理上游MCP

此服务器可以将其他MCP服务器作为子流程生成，并通过其自己的工具列表显示其工具，因此Claude Code只需要 一个MCP注册 访问设备+WiFi+SMS+UI原语+浏览器自动化。典型的例子是用微软的 @playwright/mcp 用于DOM级别的浏览器控制。

如何启用

设置 UPSTREAM_MCP 环境变量。两种可接受的格式：

# Shorthand: name=command [args...] ; ... (semicolon-separated for multiple)
UPSTREAM_MCP="playwright=npx -y @playwright/mcp@latest --headless"

# JSON: an array of { name, command, args?, env? }
UPSTREAM_MCP='[{"name":"playwright","command":"npx","args":["-y","@playwright/mcp@latest"]}]'

启动时，服务器通过stdio生成每个上游，获取其 tools/list，并在其自己的表面上注册每个工具。对代理工具的调用是透明转发的——客户端看到一个服务器。

工具名称冲突

如果上游的工具名称与本机工具或另一个上游的工具冲突，则代理会在其前加上前缀 __示例：一个假设的秒 device_list 来自一个名为 playwright 成为 playwright__device_list.

健康可观察性

HTTP /health 每个上游状态的端点报告(connected / disconnected / failed，加 toolCount 最后一个错误）。Stdio模式在启动时将相同内容记录到stderr。

根据上游环境覆盖

今日认可：

生命周期

上游在服务器启动时就开始了。开 SIGINT / SIGTERM 服务器干净地关闭所有上游子进程。

经核实的成分

默认值 UPSTREAM_MCP 在 .env.example 是 @playwright/mcp --使用该设置运行我们的服务器会产生 总共53个工具 （32名本地人+21名来自 @playwright/mcp)，所有这些都可以从一个MCP端点访问。看 cicd/tests/testcases/proxy/TC-PROXY-002.yml 用于端到端烟雾测试。

测试

YAML驱动的测试框架 cicd/tests/ 在连接的Android设备上运行。每个测试步骤都会生成自己的服务器（HTTP传输、操作系统分配的端口），因此每个测试 UPSTREAM_MCP env隔离的工作方式与stdio下相同。

在本地运行烟雾测试

# from repo root, one-time setup
npm install && npm run build
cd cicd/tests && npm install

# run the smoke suite
npm test                    # all tests
npm run test:smoke          # smoke suite only
npx tsx src/cli.ts list     # list available test cases
npx tsx src/cli.ts run --id TC-SMK-001   # one specific test

结果登陆 cicd/results/_/ (summary.json 加一 .json 每次测试）。

跑步者的工作原理

• mcp-client.ts 生成 node dist/index.js （HTTP，操作系统分配的端口），等待stderr上的监听线路，通过连接 StreamableHTTPClientTransport，调用一个工具，打印JSON结果，然后关闭服务器。每个测试步骤都是一个这样的调用。
• executor.ts 在每次测试前快照WiFi状态（启用标志、当前SSID、保存的网络ID），并在测试后恢复-- 每次测试，所以失败的测试不能毒害下一个。快照/还原完成 adb 这样框架就不会依赖于被测试的东西。
• simple-judge.ts 根据退出代码+决定通过/失败 expectPatterns/rejectPatterns.

测试套件

添加新的测试用例

使用 ci-testcase 技能(.claude/skills/ci-testcase/SKILL.md)--它为正确的套件生成正确形状的YAML。模式匹配gotcha：工具输出是双重编码的JSON，因此使用 裸弦 在图案中(connected.*true，不 '"connected": true').

CI

GitHub操作工作流 .github/workflows/:

• build.yml --在github托管的runners上运行 npm ci + tsc --noEmit + npm run build无需任何设备。
• test-run.yml --可重复使用， runs-on: self-hosted，需要a tag 输入。要求跑步者具备 adb 已安装，并连接了一个Android设备USB。
• test-smoke.yml --电话 test-run.yml 和 tag: smoke.
• ci.yml --编排。 仅手动触发 (workflow_dispatch)--链构建→ 测试烟雾。

局限性

• 需要安卓11+：The cmd wifi 接口需要Android 11（SDK 30）或更高版本
• 企业WiFi需要配套应用程序：802.1X/EAP身份验证需要安装配套应用程序
• 需要USB：设备必须通过USB连接，并启用调试
• 无专属门户自动化：可以检测但不能自动登录门户

项目结构

android-wifi-mcp/
├── src/
│   ├── index.ts                # Entry — HTTP server bootstrap
│   ├── server.ts               # MCP server factory + tool registrations
│   ├── types.ts                # TypeScript interfaces
│   ├── mcp/
│   │   └── upstream-proxy.ts   # Spawn + proxy other MCP servers (@playwright/mcp etc.)
│   ├── adb/
│   │   ├── adb-client.ts       # ADB command wrapper
│   │   ├── device-manager.ts   # Multi-device handling
│   │   ├── wifi-commands.ts    # cmd wifi wrapper
│   │   ├── screenshot-commands.ts # screencap wrapper
│   │   ├── settings-commands.ts   # adb shell settings get/put
│   │   ├── file-commands.ts       # adb push / adb pull
│   │   ├── sms-commands.ts     # SMS read / OTP polling via content provider
│   │   ├── notifications-commands.ts # Notification capture via companion app
│   │   └── enterprise-wifi.ts  # 802.1X enterprise WiFi
│   └── network/
│       └── network-check.ts    # Network diagnostics
├── companion-app/              # Android companion app for 802.1X
│   ├── app/src/main/kotlin/    # Kotlin source files
│   └── build.gradle.kts        # Gradle build config
├── docs/
│   └── integrations/           # Notes on composing with mobile-mcp / playwright-android
├── cicd/
│   ├── tests/                  # YAML-driven test framework (see Testing)
│   │   ├── src/
│   │   │   ├── cli.ts
│   │   │   ├── executor.ts     # per-test snapshot/restore of device state
│   │   │   ├── device-state.ts # adb-direct snapshot/restore helpers
│   │   │   ├── mcp-client.ts   # HTTP MCP client (spawns server, waits for ready, calls)
│   │   │   ├── loader.ts, judge/, reporter/, types.ts, config.ts
│   │   │   └── ...
│   │   ├── testcases//  # smoke, sms, notifications, proxy (wifi/enterprise/portal pending)
│   │   └── fixtures/           # mock-mcp-upstream.mjs (used by TC-PROXY-001)
│   └── results/                # JSON per-run results
├── .github/workflows/          # build.yml, test-run.yml, test-{smoke,sms,notifications,proxy}.yml, ci.yml
├── .claude/skills/             # ci-testcase, ci-run
├── .env.example
├── package.json
├── tsconfig.json
└── README.md

许可证

麻省理工学院