WaveXisMCP

MCP 服务 — 为大模型提供 220 个浏览器自动化工具

Chrome + Firefox · CDP + BiDi · 100% Python · 无需 Node.js · 无需下载 Chromium

---

English | 简体中文 | 日本語

为大模型提供 wavexis 浏览器自动化库的 MCP 服务。涵盖 13 个功能层级的 220 个工具。无需 Node.js，无需下载 Chromium——直接使用你现有的 Chrome/Edge。100% Python。

快速演示

30 秒即可生成第一张截图。 将以下内容添加到你的 MCP 客户端配置中（Claude Desktop、Cursor、Windsurf、VS Code）：

{
  "mcpServers": {
    "wavexis": {
      "command": "uvx",
      "args": ["wavexis-mcp", "--caps", "all"]
    }
  }
}

然后向你的大模型提出要求：

“截取 https://example.com 的整页截图”

大模型会调用 wavexis_screenshot(url="https://example.com", full_page=true) 并返回截图。无需 Node.js，无需下载 Chromium，除上述配置外无需其他设置。

为什么选择 WaveXisMCP？

WaveXisMCP 封装了 wavexis 浏览器自动化库，并将其作为 MCP 服务提供。你无需 Node.js、Playwright 或单独下载 Chromium——WaveXisMCP 会直接启动你现有的 Chrome 或 Edge。

主要功能

• 220 个工具 — 数量是 Playwright MCP（21 个）的 3 倍，是 zendriver-mcp（96 个）的 2 倍
• 13 个功能层级 — 通过 --caps 仅启用所需功能。从 core（72 个工具）开始，再按需添加其他层级
• Chrome + Firefox — Chrome/Edge 使用 CDP，Firefox 使用 BiDi。两者都会从 PATH 自动启动各自的驱动程序
• 无需下载 Chromium — 使用你现有的浏览器。安装大小约为 5MB，而 Playwright MCP 约为 400MB
• 隐身模式 — stealth=true 会隐藏 navigator.webdriver，伪造插件、语言和 Chrome 运行时信息
• 结构化错误 — 每个错误都包含 suggestion 字段，让大模型无需人工帮助即可自行纠正
• 多操作 YAML — 在一次工具调用中串联 navigate → click → fill → screenshot
• 原始 CDP/BiDi 访问 — 可用于访问任何没有专用工具支持的浏览器功能
• Lighthouse 审计、WebAuthn、Bluetooth、Cast — 其他 MCP 服务均未涵盖的冷门功能
• SSRF 防护、路径沙箱、速率限制 — 从一开始就内置安全防护
• 700 多项测试、强制执行 90% 覆盖率、使用真实 Chrome 进行 E2E 测试 — 可用于生产环境

工作原理

You (natural language)
  → LLM decides which tool to call
    → WaveXisMCP receives the tool call
      → wavexis library executes it via CDP or BiDi
        → Chrome/Edge/Firefox performs the action
      ← Result returned as JSON (text, base64, file path)
    ← JSON passed back to LLM
  ← LLM summarizes the result for you

大模型不会直接看到浏览器，只会看到工具定义（名称、描述、参数）和 JSON 响应。这意味着任何兼容 MCP 的大模型客户端都可以开箱即用，无需自定义集成。

核心概念

• 工具 — 单个浏览器操作（截图、eval、点击等），作为 MCP 工具提供，任何大模型客户端都可以调用。
• 会话 — 持久化的浏览器实例。打开会话，串联多个工具调用，完成后关闭。可避免每次操作都启动浏览器的开销。
• 无状态模式 — 使用 url 参数调用任意工具。浏览器会自动启动、执行并关闭。
• 能力层级 — 共 13 个层级，从 core（72 个工具）到 all（220 个工具）。通过 --caps 仅启用所需功能。
• 双后端 — CDP（基于 Chromium，通过 cdpwave）和 BiDi（W3C 跨浏览器，通过 bidiwave），可为每个会话单独选择。
• 结构化错误 — 每个错误都包含 suggestion 字段，告知大模型下一步该怎么做，从而无需人工介入即可自我纠正。

安装

pip install wavexis-mcp

默认包含 CDP 后端（Chromium）。如需使用 BiDi 后端（Firefox）：

pip install "wavexis-mcp[bidi]"

也可以不安装，直接运行（推荐）：

uvx wavexis-mcp

要求

• Python：3.11、3.12 或 3.13
• 浏览器：Google Chrome、Microsoft Edge 或任何基于 Chromium/Chrome 的浏览器
• BiDi 后端（可选）：Chrome 需使用 ChromeDriver/EdgeDriver，Firefox 需使用 geckodriver

快速开始

添加到 MCP 客户端配置中（Claude Desktop、Cursor、Windsurf、VS Code）：

{
  "mcpServers": {
    "wavexis": {
      "command": "uvx",
      "args": ["wavexis-mcp", "--caps", "all"]
    }
  }
}

或使用 pip：

{
  "mcpServers": {
    "wavexis": {
      "command": "wavexis-mcp",
      "args": ["--caps", "all"]
    }
  }
}

无状态模式（单次调用）

使用 url 参数调用任意工具 — 浏览器会自动启动、执行并关闭：

wavexis_screenshot(url="https://example.com", full_page=true)

会话模式（多步操作）

打开会话，串联多个操作，完成后关闭：

wavexis_session_open(backend="cdp", headless=false)
→ {"session_id": "abc-123"}

wavexis_navigate(session_id="abc-123", url="https://example.com")
wavexis_click(session_id="abc-123", selector="#login")
wavexis_screenshot(session_id="abc-123")
wavexis_session_close(session_id="abc-123")

自然语言交互（M1）

使用 wavexis_act 通过自然语言与页面交互：

wavexis_session_open(backend="cdp")
wavexis_navigate(session_id="abc-123", url="https://example.com")
wavexis_act(session_id="abc-123", instruction="click the login button")
→ {"action": "click", "element": {"ref": "el-3", "role": "button", "name": "Login"}, "status": "ok"}

wavexis_act 工具会获取 a11y 快照，使用关键词评分将指令与元素匹配，并执行检测到的操作（点击、输入、填写、悬停）。不会调用外部大模型 — 纯启发式匹配。

能力层级

层级	标志	工具数	主要功能
Core	始终启用	72	会话、导航、截图、PDF、抓取、eval、DOM、输入、Cookie、标签页、自然语言交互、iframe、shadow DOM、事件
Network	--caps=network	20	标头、UA、阻止、限流、缓存、HAR、拦截、模拟、修改请求/响应、请求正文、重放 HAR、请求列表
Storage	--caps=storage	18	localStorage、sessionStorage、缓存存储、IndexedDB、状态保存/恢复
Emulation	--caps=emulation	9	设备、视口、地理位置、时区、深色模式、区域设置、CPU、触控、传感器
A11y	--caps=a11y	4	无障碍树快照、节点遍历、axe-core 审计
Interactions	--caps=interactions	5	对话框、下载、权限
DevTools	--caps=devtools	31	性能、CSS、调试、叠加层、控制台、安全、窗口管理、组合跟踪、带注释的截图
Vision	--caps=vision	7	基于坐标的鼠标操作（像素级精确）
Video	--caps=video	4	视频录制、章节、操作叠加层
Testing	--caps=testing	6	断言、定位器生成
Workflows	--caps=workflows	6	多操作 YAML、原始 CDP/BiDi、浏览器上下文 CRUD
Data	--caps=data	7	代码生成、Lighthouse 审计、提取、WebSocket 拦截、爬取、视觉差异、核心 Web 指标
Experimental	--caps=experimental	31	Service Worker、动画、WebAuthn、WebAudio、媒体、投屏、蓝牙、扩展、首选项
总计	--caps=all	220

默认值：--caps=core（72 个工具）。启用全部功能：--caps=all。启用指定功能：--caps=network,storage,emulation。

提示：从 --caps core 开始，并按需添加层级。每个层级都会向大模型上下文中添加工具定义，从而消耗令牌。对于大多数任务，core,network,storage（110 个工具）是不错的平衡选择。

后端

WaveXisMCP 支持两种功能完全对等的后端：

• CDP（cdpwave）——默认后端，Chrome DevTools Protocol。通过 WebSocket 直接连接 Chrome/Edge。无需驱动程序。支持 57 个 CDP 域。默认包含。
• BiDi（bidiwave）——WebDriver BiDi 协议，支持 W3C 跨浏览器（Firefox、Chrome）。需要 chromedriver（Chrome）或 geckodriver（Firefox）；如果驱动程序尚未运行，会自动从 PATH 启动。pip install "wavexis-mcp[bidi]"

按会话选择：

# CDP (default, Chrome/Edge only)
wavexis_session_open(backend="cdp")

# BiDi with Chrome (auto-launches chromedriver)
wavexis_session_open(backend="bidi", browser="chrome")

# BiDi with Firefox (auto-launches geckodriver)
wavexis_session_open(backend="bidi", browser="firefox")

连接到现有 Chrome

使用 connect_existing=True 启动 Chrome 时添加 --remote-debugging-port 并连接到该浏览器。适用于复用已登录的浏览器配置文件：

# Launch Chrome with debug port and connect via CDP
wavexis_session_open(connect_existing=true)

# Reuse an existing Chrome profile (keeps logins, cookies, extensions)
wavexis_session_open(connect_existing=true, user_data_dir="C:/Users/me/ChromeProfile")

Chrome 会以有头模式启动（忽略无头模式设置）。关闭会话时会终止浏览器子进程。

多操作 YAML

传入 YAML 字符串，即可在一次工具调用中串联多个操作：

wavexis_multi_action(
    config="""
actions:
  - navigate: https://example.com
  - screenshot:
      full_page: true
  - eval: document.title
  - click: "#login"
  - type:
      selector: "#username"
      text: [email protected]
  - screenshot: {}
""",
    session_id="abc-123"
)

支持的操作类型：navigate、screenshot、eval、click、type、fill。设置 continue_on_error: true 可在发生错误时继续执行。

MCP 资源与提示词（M3）

资源（只读浏览器状态）：

• wavexis://session/{id}/url — 当前页面 URL
• wavexis://session/{id}/cookies — JSON 格式的 Cookie
• wavexis://session/{id}/console — 控制台消息
• wavexis://session/{id}/tabs — 已打开的标签页

提示词（工作流模板）：

• scrape_page(url, selector) — 抓取并提取内容
• audit_page(url) — 全面的无障碍与性能审计
• fill_form(url, fields) — 填写页面上的表单
• debug_page(url) — 调试控制台、网络和性能

HTTP 传输

将 WaveXisMCP 作为 HTTP 服务运行，用于 CI/CD、共享实例或 Docker：

# HTTP on localhost
wavexis-mcp --transport http --port 8765

# HTTP with all tiers
wavexis-mcp --transport http --port 8765 --caps all

# HTTP with remote access (use behind a reverse proxy!)
wavexis-mcp --transport http --allow-remote --port 8765

默认绑定到 127.0.0.1。使用 --allow-remote 可绑定到 0.0.0.0。

速率限制（M4）

按会话进行令牌桶速率限制：

# 10 calls/sec, burst of 5
wavexis-mcp --rate-limit 10 --rate-burst 5

超过限制时，工具会返回标准结构化错误：{"error": "Rate limit exceeded. Retry after Nms.", "type": "RuntimeError", ...}。设置 --rate-limit 0 可禁用此功能。

Docker

# Pull and run
docker run -p 8765:8765 ghcr.io/mathiaspaulenko/wavexis-mcp

# Or build locally
docker build -t wavexis-mcp .
docker run -p 8765:8765 wavexis-mcp

# Docker Compose
docker-compose up

详情请参阅 Docker 文档。

对比

功能	Playwright MCP	WaveXisMCP
语言	TypeScript	Python
是否需要 Node.js	✗	✓（无需 Node.js）
下载 Chromium（约 200 MB）	✓	✗（使用现有浏览器）
安装大小	约 400 MB	约 5 MB
冷启动	3.2 秒	0.8 秒
工具总数	约 21	220
能力层级（选择启用）	✗	✓（13 个层级）
双协议（CDP + BiDi）	✗	✓
Firefox 支持	✓（基础）	✓（BiDi + 自动启动 geckodriver）
后端选择（按会话）	✗	✓
隐身／反机器人模式	✗	✓
原始 CDP/BiDi 访问	✗	✓（备用通道）
多操作 YAML 批处理	✗	✓
视频录制	✗	✓
Lighthouse 审计	✗	✓
WebAuthn／Bluetooth／Cast	✗	✓
自然语言交互	✗	✓（wavexis_act）
MCP 资源与提示词	✗	✓
速率限制	✗	✓
SSRF 防护	✗	✓
带建议的结构化错误	✗	✓

注意：Playwright MCP 支持 WebKit（Safari），WaveXisMCP 目前尚不支持。计划中的功能请参阅路线图。

文档

完整文档、API 参考和示例托管在 mathiaspaulenko.github.io/wavexis-mcp。

主要章节：

• 快速入门
• 架构
• 配置
• Docker
• HTTP 传输
• 速率限制
• 工具参考
• 示例

错误处理

所有工具在失败时都会返回结构化的错误 JSON。每个错误都包含一个 suggestion 字段，用于引导 LLM 采取下一步操作：

{
  "error": "Session 'abc-123' not found.",
  "tool": "wavexis_navigate",
  "type": "SessionNotFoundError",
  "message": "Session 'abc-123' not found.",
  "suggestion": "Call wavexis_session_open first to create a browser session."
}

这使 LLM 能够在无需人工干预的情况下自行纠正——它会读取建议并调用推荐的工具。

架构

WaveXisMCP 位于由三层组成的生态系统顶层：

WaveXisMCP (MCP server, 220 tools)
└─ wraps → wavexis (browser automation library)
               ├─ cdpwave (CDP backend, Chromium-native)
               └─ bidiwave (BiDi backend, W3C cross-browser)

• cdpwave — 用于 Chrome DevTools Protocol 的底层异步 Python 库。通过 WebSocket 直接连接 Chrome/Edge。无需驱动程序二进制文件。
• bidiwave — 用于 WebDriver BiDi 协议（W3C 标准）的底层异步 Python 库。支持 Firefox、Chrome 和 Edge。
• wavexis — 高层浏览器自动化库，通过统一的 AbstractBackend 接口抽象 cdpwave 和 bidiwave。
• WaveXisMCP — 封装 wavexis 的 MCP 服务。将每个后端方法作为 MCP 工具公开，并提供 Pydantic v2 输入验证、JSON 响应和能力层级筛选。

如需了解完整的系统设计、数据流图和 ADR，请参阅架构文档。

开发

git clone https://github.com/MathiasPaulenko/wavexis-mcp.git
cd wavexis-mcp
pip install -e ".[dev]"

# Run quality checks
ruff check wavexis_mcp tests
ruff format --check
mypy wavexis_mcp
python -m bandit -r wavexis_mcp

# Run tests
pytest tests/unit -v

贡献

欢迎贡献。有关开发工作流、编码规范和拉取请求流程，请参阅 CONTRIBUTING.md。有关安全问题，请参阅 SECURITY.md。

致谢

WaveXisMCP 基于浏览器自动化库 wavexis 和 Model Context Protocol 构建。感谢开源 Python 和 MCP 社区提供的工具与标准，让本项目得以实现。

许可证

MIT

mcp-name: io.github.MathiasPaulenko/wavexis-mcp