ruyipage-mcp
ruyipage-mcp
将 ruyiPage 的 Firefox BiDi 自动化能力,通过 MCP (Model Context Protocol) 暴露为 AI 可调用的工具集。
支持 Claude Code、Cursor 等任意 MCP 客户端。
特性
34 个工具,覆盖浏览器自动化全流程:启动/接管浏览器、页面导航、DOM 查找与交互、截图/PDF、Cookie/Storage、JS 执行、网络拦截/监听/数据采集、标签页管理、设备模拟、BiDi 事件订阅
原生 BiDi 动作优先 — 点击、输入、拖拽等操作保持
isTrusted=true,更适合高风控场景支持接管指纹浏览器 — 可自动探测并接管 ADS / FlowerBrowser 等 Firefox 内核指纹浏览器
智能元素管理 — LRU 元素注册表,自动回收 + 过期元素自动重查
截图自动压缩 — 超宽图片自动缩放,JPEG 压缩,大图自动落盘
stdio 传输 — 标准 JSON-RPC 2.0,开箱即用
Related MCP server: MCP Selenium Server
安装
前置要求
Python >= 3.10
ruyiPage >= 1.1.0
Firefox 浏览器(推荐使用 ruyiPage 配套的 Firefox 内核)
从源码安装
git clone https://github.com/LoseNine/ruyipage-mcp.git
cd ruyipage-mcp
pip install -e .也可以直接把github连接给ai,让ai帮你装
配置
Claude Code
方式一: 项目级 .mcp.json(推荐)
{
"mcpServers": {
"ruyipage": {
"command": "python",
"args": ["-m", "ruyipage_mcp"]
}
}
}Cursor / 其他 MCP 客户端
在对应 MCP 配置文件中添加:
{
"mcpServers": {
"ruyipage": {
"command": "python",
"args": ["-m", "ruyipage_mcp"]
}
}
}独立运行
python -m ruyipage_mcp服务器通过 stdin/stdout 传输 JSON-RPC 消息,日志输出到 stderr。
配置
配置文件
将 ruyipage_mcp.example.json 复制为 ruyipage_mcp.json,按需修改:
cp ruyipage_mcp.example.json ruyipage_mcp.json{
"browser_path": "E:\\ruyi_firefox\\firefox.exe",
"disable_run_js": false,
"disable_extensions": false,
"browser_path_whitelist": [],
"max_elements": 512,
"event_buffer_size": 500,
"wait_timeout_ceiling": 60
}配置文件查找顺序:
RUYIPAGE_MCP_CONFIG环境变量指定的路径当前工作目录下的
ruyipage_mcp.json若未找到配置文件,使用内置默认值
配置项 | 类型 | 默认值 | 说明 |
| string |
| Firefox 可执行文件路径 |
| bool |
| 设为 |
| bool |
| 设为 |
| list |
| 允许的浏览器路径列表 |
| int |
| 每个会话的元素注册表 LRU 容量 |
| int |
| BiDi 事件缓冲区大小 |
| int |
| 所有等待类工具的超时上限(秒) |
环境变量覆盖
环境变量优先级高于配置文件,适合 CI 或临时覆盖场景:
环境变量 | 对应配置项 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 指定配置文件路径 |
工具一览 (34 个)
session — 浏览器生命周期
工具 | 说明 |
| 启动新 Firefox 浏览器。支持自定义端口、无头模式、隐私模式、XPath Picker、窗口大小等 |
| 通过 |
| 按进程特征自动探测并接管 Firefox / ADS / FlowerBrowser |
| 关闭浏览器会话。 |
典型流程:
session_launch(port=9222)
→ 操作页面...
→ session_quit()# 接管已打开的指纹浏览器
session_auto_attach(latest_tab=true)
→ 操作页面...
→ session_quit() # 仅释放连接,浏览器继续运行nav — 页面导航
工具 | 说明 |
| 打开 URL,支持 |
| 后退 |
| 前进 |
| 刷新 |
| 获取当前页面的 URL、标题、ready state |
dom — 元素查找与读取
工具 | 说明 |
| 查找单个元素,返回 |
| 查找所有匹配元素,返回列表(默认上限 20,最大 100) |
| 读取元素属性: |
| 在已有元素内部继续查找子元素 |
| 等待元素出现(带超时) |
| 释放元素句柄,回收注册表空间 |
定位器格式:
格式 | 示例 | 说明 |
|
| ID 选择器 |
|
| CSS 选择器 |
|
| XPath |
|
| 文本匹配 |
|
| 标签名 |
act — 元素交互
工具 | 说明 |
| 点击元素。支持左键 / 右键 / 双击,可选 JS 点击。默认使用原生 BiDi 动作 ( |
| 输入文本。原生 BiDi 键盘输入,可选清空已有内容。支持 JS 回退 |
| 简单操作: |
| 执行 BiDi 动作链(JSON 数组),支持按键、点击、移动、拖拽、滚轮、暂停等 |
act_chain 支持的动作:
[
{"action": "press", "key": "Enter"},
{"action": "click"},
{"action": "click", "element_id": "el_abc123"},
{"action": "move_to", "element_id": "el_abc123"},
{"action": "move_to", "x": 100, "y": 200},
{"action": "double_click"},
{"action": "right_click"},
{"action": "key_down", "key": "Shift"},
{"action": "key_up", "key": "Shift"},
{"action": "type", "text": "hello"},
{"action": "scroll", "x": 0, "y": -300},
{"action": "pause", "duration": 500}
]state — 页面状态
工具 | 说明 |
| 截图。支持全页面截图、元素截图、保存到文件。自动压缩,超大图自动落盘 |
| 将当前页面保存为 PDF |
| Cookie 管理: |
| localStorage / sessionStorage 管理: |
js — JavaScript 执行
工具 | 说明 |
| 在页面中执行 JS 代码。可作为表达式求值 ( |
| 管理 preload script: |
net — 网络控制
工具 | 说明 |
| 请求拦截: |
| 网络监听: |
| 数据采集器: |
| 设置/清除额外请求头 |
| 设置缓存行为: |
请求拦截典型流程:
net_intercept(op="start", url_patterns="api/login")
→ 触发页面操作
→ net_intercept(op="wait_and_resolve", action='{"mode":"mock","status":200,"body":"{}"}')
→ net_intercept(op="stop")网络监听典型流程:
net_listen(op="start", targets="api/data", method="POST")
→ 触发页面操作
→ net_listen(op="wait", timeout=10)
→ net_listen(op="stop")ctx — 上下文管理
工具 | 说明 |
| 标签页管理: |
| 设备模拟:地理位置、时区、语言、移动设备预设、离线模式、JS 开关 |
| BiDi 事件订阅:统一入口管理 |
模拟操作示例:
ctx_emulation(op="set_geolocation", latitude=39.9, longitude=116.4)
ctx_emulation(op="set_timezone", timezone_id="Asia/Tokyo")
ctx_emulation(op="set_locale", locales="ja-JP,ja")
ctx_emulation(op="apply_mobile_preset", width=390, height=844, device_pixel_ratio=3)
ctx_emulation(op="set_offline", enabled=true)
ctx_emulation(op="set_offline", enabled=false)meta — 服务器信息
工具 | 说明 |
| 返回当前服务器状态:活跃会话、元素数量、配置开关、工具命名空间列表 |
核心概念
会话管理
每个浏览器连接对应一个 session,以 host:port(如 127.0.0.1:9222)作为标识。
当只有一个活跃 session 时,所有工具的
session_id参数可省略,自动解析有多个 session 时,需要显式传入
session_idsession_launch创建的是 owned 会话,session_quit会终止浏览器进程session_attach/session_auto_attach创建的是 attached 会话,session_quit仅释放连接
元素注册表
通过 dom_find / dom_find_all 查到的元素会被注册到当前 session 的元素注册表中,返回一个短 ID(如 el_a3f2b1)。
LRU 回收 — 达到容量上限(默认 512)时,最久未使用的元素自动回收
过期自动恢复 — 访问过期元素时,自动尝试用原始定位器重新查找
元素 ID 可传给
act_click、act_input、dom_read、act_chain等所有需要元素引用的工具所有接受
target参数的工具也可直接传入定位器字符串(如css:button.submit),无需先调用dom_find
响应格式
所有工具(state_screenshot 除外)返回统一 JSON 信封:
// 成功
{"ok": true, "data": ...}
// 失败
{"ok": false, "error": "error message"}state_screenshot 在截图体积允许时直接返回 MCP Image 对象;超过 800KB 时落盘返回文件路径。
配套项目
ruyiPage — 核心 Firefox BiDi 自动化库
ruyipage-skill — AI 自动化分析运行 Skill
Firefox 指纹浏览器 — 配套 Firefox 指纹环境
架构
python -m ruyipage_mcp
→ __main__.py → server.run()
→ 导入 tools/*.py(触发 @mcp.tool() 注册 34 个工具)
→ 注册 atexit 清理(退出时关闭 owned 浏览器)
→ mcp.run(transport="stdio")
ruyipage_mcp/
├── app.py # FastMCP("ruyipage-mcp") 单例
├── config.py # 环境变量配置
├── registries.py # SessionRegistry + ElementRegistry (LRU)
├── runtime.py # async/sync 桥接 + 响应封装 + 元素解析
├── server.py # 入口 + atexit 清理
└── tools/
├── session.py # 浏览器启动/接管/关闭
├── nav.py # 页面导航
├── dom.py # 元素查找/读取
├── act.py # 元素交互/动作链
├── state.py # 截图/PDF/Cookie/Storage
├── js.py # JS 执行/预加载脚本
├── net.py # 网络拦截/监听/采集
├── ctx.py # 标签页/模拟/事件
└── meta.py # 服务器状态ruyiPage 是同步库,MCP FastMCP 是 asyncio。所有 ruyiPage 调用通过 asyncio.to_thread() 桥接,确保 MCP 事件循环不被阻塞。
使用声明
本项目遵循 ruyiPage 的使用声明,仅限合法、合规、非盈利的个人研究与技术交流用途。
License
BSD-3-Clause
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Live browser debugging for AI assistants — DOM, console, network via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server paired with a Firefox extension that enables LLM clients to control the user's browser, supporting tab management, history search, and content reading.353MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server implementation that enables browser automation through standardized MCP clients, supporting features like navigation, element interaction, and screenshots across Chrome, Firefox, and Edge browsers.MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP Server that enables AI assistants to interact with your local browsers.55MIT
- AlicenseCqualityCmaintenanceEnables AI assistants to read and drive a real, logged-in Firefox browser, including tabs, cookies, history, and site interactions, all through the Model Context Protocol.5216 npmMIT