XBrowser Controller - X浏览器深度控制技能

X浏览器（com.mmbox.xbrowser）的完整逆向理解、APK 改造能力、以及通过内置 MCP 服务器直接控制浏览器的能力。

掌握 404 个原生桥方法、APK 改造能力、439 个 MCP 工具，可通过 HTTP 直接操控 X浏览器。

功能特性

• 通过 MCP HTTP 服务器直接控制 X浏览器
• 8 个基础工具：状态查询、标签页信息、执行JS、获取HTML、获取文本、枚举桥方法、导航、刷新
• 27 个高级封装工具：系统信息、UI主题、弹窗、剪贴板、搜索、UA管理、代理、阅读模式、媒体/TTS、下载管理、文件管理、书签、账户、VIP、自动填充、站点策略、隐私、标签管理、手势、事件、QR扫描、分享、缩放、安全、用户脚本、开发者工具、广告拦截
• 404 个原生桥方法直接调用
• 支持局域网直连和 ADB 隧道两种连接方式
• 技能定义文件，可直接集成到 AI Agent 系统

前置条件

1. X浏览器增强版 APK（已内置 MCP HTTP 服务器，端口 8765）
2. Python 3.8+
3. 网络连接（局域网或 ADB）

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 启动 X浏览器 MCP 服务器

在 X浏览器增强版中，浏览器启动后自动监听端口 8765。

确认 MCP 服务器运行：

curl -X POST http://127.0.0.1:8765/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"xbrowser_status","arguments":{}}}'

3. 使用 Python 客户端

from xbrowser_mcp_server import XBrowserClient

# 连接 X浏览器 MCP 服务器
client = XBrowserClient("http://127.0.0.1:8765/mcp")

# 查询状态
status = client.call_tool("xbrowser_status")
print(status)

# 导航到网页
client.call_tool("xbrowser_navigate", {"url": "https://www.baidu.com"})

# 获取页面内容
html = client.call_tool("xbrowser_get_html")
print(html)

# 执行 JavaScript
result = client.call_tool("xbrowser_eval_js", {"expression": "document.title"})
print(result)

# 获取 Cookie
cookies = client.call_tool("xbridge_GM_cookie_list", {"p1": "", "p2": "", "p3": "", "p4": ""})
print(cookies)

# TTS 语音朗读
client.call_tool("xbridge_TTS", {"p1": "你好，这是语音朗读测试"})

4. 命令行使用

# 查询状态
python xbrowser_mcp_server.py status

# 导航
python xbrowser_mcp_server.py navigate https://www.baidu.com

# 获取页面文本
python xbrowser_mcp_server.py text

# 执行JS
python xbrowser_mcp_server.py eval "document.title"

连接方式

局域网直连

POST http://192.168.1.5:8765/mcp
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"xbrowser_status","arguments":{}}}

ADB 隧道（如局域网不通）

adb forward tcp:8765 tcp:8765
# 然后访问 http://127.0.0.1:8765/mcp

工具清单

一、基础工具（8个）

工具	参数	说明
xbrowser_status	无	返回 {running, port, webview}
xbrowser_tab_info	无	返回当前标签页 {title, url, mbrowser}
xbrowser_eval_js	expression	执行任意 JavaScript
xbrowser_get_html	无	返回页面 HTML 源码
xbrowser_get_text	无	返回页面可见文本
xbrowser_bridge_methods	无	枚举全部 404 个桥方法名
xbrowser_navigate	url	导航到指定 URL
xbrowser_reload	无	刷新当前页面

二、高级封装工具（27个）

每个工具通过 action 参数区分子操作，包括：系统信息、UI主题、弹窗、剪贴板、搜索、UA管理、代理、阅读模式、媒体/TTS、下载管理、文件管理、书签、账户、VIP、自动填充、站点策略、隐私、标签管理、手势、事件、QR扫描、分享、缩放、安全、用户脚本、开发者工具、广告拦截。

三、桥方法工具（404个）

命名规则：xbridge_<方法名>，参数按顺序传 p1, p2, p3...

常见可用桥方法：

• xbridge_getVersionCode -> 版本号
• xbridge_getBrowserInfoObj -> 浏览器信息
• xbridge_inChina -> 是否在中国
• xbridge_GM_cookie_list(p1,p2,p3,p4) -> 列出 Cookie（含 httpOnly）
• xbridge_getFaviconURI(p1) -> 获取网站图标
• xbridge_getElementRules(p1) -> 获取广告过滤规则
• xbridge_getSniffMediaResource -> 嗅探媒体资源
• xbridge_TTS(p1) -> 语音朗读文本

安全校验说明

约 1/4 的桥方法受 X8.p() 安全校验保护，只允许在以下页面调用：

• x:// 内部协议页面（如 x://settings）
• file:///android_asset/ 设置页
• xbext.com 域名

解决方案：先 xbrowser_navigate("x://settings") 再调用受限方法。

APK 改造知识

工具链

# 编译 Java
javac -cp /opt/android-sdk/platforms/android-34/android.jar -d out com/mmbox/xbrowser/XBrowserMcpServer.java

# 转换为 DEX
java -cp /opt/android-sdk/build-tools/35.0.0/lib/d8.jar com.android.tools.r8.D8 \
  --output dex_out --lib /opt/android-sdk/platforms/android-34/android.jar \
  out/com/mmbox/xbrowser/*.class

# 反编译 DEX
java -cp /usr/share/java/baksmali.jar:... org.jf.baksmali.Main \
  disassemble -o smali_out dex_out/classes.dex

# 打包 APK
apktool b $DECODED_DIR -o output.apk

# 签名
java -jar /opt/android-sdk/build-tools/35.0.0/lib/apksigner.jar sign \
  --ks /tmp/debug.keystore --ks-pass pass:android \
  --out signed.apk unsigned.apk

# 安装
adb install -r signed.apk

修改点

1. Browser.smali -> onCreate() 注入 getInstance() -> setContext() -> start()
2. Of.smali -> 构造函数注入 getInstance() -> registerWebView(webView)
3. X8.smali -> 追加 enableMcpServer(boolean) 和 isMcpServerEnabled() 桥方法
4. assets/settings/general-setting.html -> 注入 MCP 开关 UI + JS

已知问题

问题	原因	解决
requests.post(json=...) 失败	服务器 jsonGetString 不支持空格	用 data= 传 JSON + separators
端口 8765 被占用	旧 Python MCP 残留	pkill -f xbrowser_mcp 后再重启
局域网直连断	无线调试端口过期	重启浏览器或重建 ADB forward

项目结构

xbrowser_controller/
├── README.md                  # 项目说明
├── LICENSE                    # MIT 许可证
├── xbrowser_mcp_server.py     # MCP 服务器客户端核心代码
├── skills.json                # 技能定义（8个预置工具）
├── requirements.txt           # Python 依赖
└── .gitignore

技能定义

skills.json 包含 8 个预置工具的完整定义，可直接集成到 AI Agent 系统：

• 查询X浏览器状态
• X浏览器导航
• X浏览器搜索
• 读取X浏览器页面内容
• 获取X浏览器Cookie
• 获取X浏览器信息
• X浏览器执行JS
• X浏览器语音朗读

注意事项

• 本工具仅用于合法的安全研究和学习
• 逆向和 APK 改造请遵守相关法律法规
• 使用本工具造成的任何后果由使用者自行承担

许可证

MIT License