ruyipage-mcp

Exposes the Firefox BiDi automation capabilities of ruyiPage as a set of tools callable by AI via the MCP (Model Context Protocol).

Supports any MCP client such as Claude Code, Cursor, etc.

Features

• 34 tools covering the entire browser automation workflow: launching/attaching to browsers, page navigation, DOM lookup and interaction, screenshots/PDFs, Cookies/Storage, JS execution, network interception/listening/data collection, tab management, device emulation, and BiDi event subscription.

• Native BiDi action priority — Actions like clicking, typing, and dragging maintain isTrusted=true, making them more suitable for high-risk control scenarios.

• Support for taking over fingerprint browsers — Automatically detects and attaches to Firefox-based fingerprint browsers like ADS / FlowerBrowser.

• Intelligent element management — LRU element registry with automatic recycling and automatic re-lookup for expired elements.

• Automatic screenshot compression — Automatic scaling for ultra-wide images, JPEG compression, and automatic disk saving for large images.

• stdio transport — Standard JSON-RPC 2.0, ready to use out of the box.

Related MCP server: MCP Selenium Server

Installation

Prerequisites

• Python >= 3.10

• ruyiPage >= 1.1.0

• Firefox browser (it is recommended to use the Firefox kernel bundled with ruyiPage)

Install from Source

git clone https://github.com/LoseNine/ruyipage-mcp.git
cd ruyipage-mcp
pip install -e .

You can also provide the GitHub link directly to the AI to have it install for you

Configuration

Claude Code

Method 1: Project-level .mcp.json (Recommended)

{
  "mcpServers": {
    "ruyipage": {
      "command": "python",
      "args": ["-m", "ruyipage_mcp"]
    }
  }
}

Cursor / Other MCP Clients

Add the following to your corresponding MCP configuration file:

{
  "mcpServers": {
    "ruyipage": {
      "command": "python",
      "args": ["-m", "ruyipage_mcp"]
    }
  }
}

Standalone Execution

python -m ruyipage_mcp

The server transmits JSON-RPC messages via stdin/stdout and outputs logs to stderr.

Configuration

Configuration File

Copy ruyipage_mcp.example.json to ruyipage_mcp.json and modify as needed:

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
}

Configuration file lookup order:

1. Path specified by the RUYIPAGE_MCP_CONFIG environment variable

2. ruyipage_mcp.json in the current working directory

3. If no configuration file is found, built-in defaults are used

Environment Variable Overrides

Environment variables have higher priority than the configuration file, suitable for CI or temporary override scenarios:

Tool Overview (34 total)

session — Browser Lifecycle

Typical workflow:

session_launch(port=9222)
  → 操作页面...
  → session_quit()

# 接管已打开的指纹浏览器
session_auto_attach(latest_tab=true)
  → 操作页面...
  → session_quit()  # 仅释放连接，浏览器继续运行

nav — Page Navigation

dom — Element Lookup and Reading

Locator format:

act — Element Interaction

Actions supported by 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 — Page State

js — JavaScript Execution

net — Network Control

Typical request interception workflow:

net_intercept(op="start", url_patterns="api/login")
  → 触发页面操作
  → net_intercept(op="wait_and_resolve", action='{"mode":"mock","status":200,"body":"{}"}')
  → net_intercept(op="stop")

Typical network listening workflow:

net_listen(op="start", targets="api/data", method="POST")
  → 触发页面操作
  → net_listen(op="wait", timeout=10)
  → net_listen(op="stop")

ctx — Context Management

Emulation example:

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 — Server Information

Core Concepts

Session Management

Each browser connection corresponds to a session, identified by host:port (e.g., 127.0.0.1:9222).

• When there is only one active session, the session_id parameter for all tools can be omitted and is resolved automatically.

• When there are multiple sessions, session_id must be explicitly passed.

• session_launch creates an owned session; session_quit will terminate the browser process.

• session_attach / session_auto_attach create an attached session; session_quit only releases the connection.

Element Registry

Elements found via dom_find / dom_find_all are registered in the current session's element registry, returning a short ID (e.g., el_a3f2b1).

• LRU Recycling — When the capacity limit (default 512) is reached, the least recently used element is automatically recycled.

• Automatic Recovery — When accessing an expired element, it automatically attempts to re-find it using the original locator.

• Element IDs can be passed to all tools requiring element references, such as act_click, act_input, dom_read, act_chain, etc.

• All tools accepting a target parameter can also directly accept a locator string (e.g., css:button.submit) without needing to call dom_find first.

Response Format

All tools (except state_screenshot) return a unified JSON envelope:

// 成功
{"ok": true, "data": ...}

// 失败
{"ok": false, "error": "error message"}

state_screenshot returns an MCP Image object directly when the screenshot size permits; if it exceeds 800KB, it is saved to disk and the file path is returned.

Related Projects

• ruyiPage — Core Firefox BiDi automation library

• ruyipage-skill — AI automation analysis and execution Skill

• Firefox Fingerprint Browser — Bundled Firefox fingerprint environment

Architecture

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 is a synchronous library, while MCP FastMCP is asyncio-based. All ruyiPage calls are bridged via asyncio.to_thread() to ensure the MCP event loop is not blocked.

Usage Statement

This project follows the usage statement of ruyiPage and is intended solely for legal, compliant, and non-profit personal research and technical exchange purposes.

License

BSD-3-Clause