跳到主要内容

OmniWeb Android控制MCP服务器

一个 MCP 服务器，封装了 OmniWeb “Android 中间件”（omniweb-android Flask 服务，/api/android/*），以便 MCP 客户端——Claude Code、Claude Desktop 或自定义客户端——可以控制 实验室的 Android 手机和 USB 调制解调器。

它是一个薄层 HTTP 客户端，基于现有的 REST API（不导入任何 Flask 内部），因此可以与任何可达的 omniweb-android 实例一起使用。

暴露的工具​

工具签名功能
list_devices()所有已知设备（手机 + 调制解调器），在线和离线。
device_info(serial)单个设备的完整详细信息。
screenshot(serial) → PNG 图像当前屏幕（通用：scrcpy 手机和旧的截屏设备）。
tap(serial, x, y)在像素坐标处点击。
swipe(serial, x1, y1, x2, y2, ms=200)滑动/拖动/抛掷。
input_text(serial, text)在聚焦字段中输入。
key(serial, name)按下返回/主页/最近/回车/删除/电源/菜单/音量增大/音量减小。
adb_shell(serial, command, timeout=30) → {stdout, stderr, return_code}任意 adb shell（强大工具）。
list_scripts()设备测试脚本库。
run_script(serials, file, params={})在设备间运行脚本；返回运行句柄。
get_run(run_id)脚本运行的结果（状态/stdout/return_code）。
at_command(serial, command, read_ms=0, timeout_ms=0)发送原始 AT 命令到 USB 调制解调器。
send_sms(serial, number, text)从调制解调器发送 SMS。

配置（环境变量）​

后端目标：

  • OMNIWEB_API_BASE — Android 服务的基本 URL。默认值 http://127.0.0.1:5002。/api/android 前缀会自动添加。

后端认证（选择一个）：

  • OMNIWEB_JWT — 预先生成的后端访问令牌（Bearer），或者
  • OMNIWEB_JWT_SECRET — 后端的 JWT_SECRET_KEY。服务器将自己生成 一个短期的管理员 JWT 并自动刷新。OMNIWEB_JWT_TTL （秒，默认 3600）控制其生命周期。

此 MCP 服务器的前门：

  • MCP_TRANSPORT — http（默认，适用于远程客户端的可流式 HTTP）或 stdio（本地 claude mcp add）。
  • MCP_HOST / MCP_PORT — http 传输的绑定地址。默认值 127.0.0.1:5005。
  • MCP_AUTH_TOKEN — 远程 MCP 客户端必须提供的 Bearer 令牌。绑定到 除 localhost 以外的任何内容时必需 — 服务器在没有它的情况下拒绝 非回环绑定（失败关闭）。在 /mcp 上，令牌由中间件检查； / 和 /health 对健康检查开放。

运行它​

venv（自包含）​

cd /opt/omniweb-mcp           # 或者你放置 server.py + requirements.txt 的地方
python3 -m venv venv
venv/bin/pip install -r requirements.txt

export OMNIWEB_API_BASE=http://127.0.0.1:5002
export OMNIWEB_JWT_SECRET=<后端 JWT_SECRET_KEY>
export MCP_TRANSPORT=http
export MCP_HOST=0.0.0.0
export MCP_PORT=5005
export MCP_AUTH_TOKEN=<一个长的随机令牌>
venv/bin/python server.py

systemd（生产）​

提供了一个单元文件在 packaging/omniweb-android-mcp.service。它读取 /etc/omniweb/omniweb.env（用于 JWT_SECRET_KEY → 它被重新导出为 OMNIWEB_JWT_SECRET，见下文）以及 /etc/omniweb/android-mcp.env 以获取 MCP 特定的秘密。创建该 drop-in（chmod 600）：

# /etc/omniweb/android-mcp.env
OMNIWEB_JWT_SECRET=<与 omniweb.env 中的 JWT_SECRET_KEY 相同的值>
MCP_AUTH_TOKEN=<一���长的随机令牌>

然后：

sudo cp packaging/omniweb-android-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now omniweb-android-mcp

后端 env 文件将 JWT 秘密命名为 JWT_SECRET_KEY；此服务器读取 OMNIWEB_JWT_SECRET。在 android-mcp.env 中显式设置 OMNIWEB_JWT_SECRET （复制该值），以便名称对齐。

从 Claude Code 连接​

远程（可流式 HTTP），带认证：

claude mcp add --transport http android-control http://<host>:5005/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

本地（stdio），将服务器指向后端并生成自己的 JWT：

claude mcp add android-control \
  -e OMNIWEB_API_BASE=http://127.0.0.1:5002 \
  -e OMNIWEB_JWT_SECRET=<后端 JWT_SECRET_KEY> \
  -e MCP_TRANSPORT=stdio \
  -- /opt/omniweb-mcp/venv/bin/python /opt/omniweb-mcp/server.py

然后在 Claude Code 中：/mcp 确认它已连接，并尝试 list_devices。

从 Claude Desktop 连接​

claude_desktop_config.json — stdio 启动：

{
  "mcpServers": {
    "android-control": {
      "command": "/opt/omniweb-mcp/venv/bin/python",
      "args": ["/opt/omniweb-mcp/server.py"],
      "env": {
        "OMNIWEB_API_BASE": "http://127.0.0.1:5002",
        "OMNIWEB_JWT_SECRET": "<后端 JWT_SECRET_KEY>",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

对于来自 Claude Desktop 的远程可流式 HTTP 服务器，使用 mcp-remote 桥接或你的桌面版本支持的 HTTP 服务器配置，指向 http://<host>:5005/mcp，并带上 Authorization: Bearer &lt;MCP_AUTH_TOKEN> 头。

安全注意事项​

  • 设备控制需要在 HTTP 传输中配置的 MCP_AUTH_TOKEN。没有令牌，服务器只允许回环绑定并打印警告；没有令牌的非回环绑定会被拒绝。
  • 服务器作为管理员（生成的 JWT 或提供的令牌）对后端进行身份验证，因此任何能够使用 Bearer 令牌访问 /mcp 的人都拥有完全的设备控制权限。将 MCP_AUTH_TOKEN 视为密码，并通过 TLS（例如，通过 nginx）进行保护，以便进行非主机访问。
最后于 更新