内容
<p align="center">
<img src="docs/assets/images/logo-wide.svg" alt="WaveXisMCP" width="480">
</p>
<h3 align="center">MCP 服务器 — 面向大语言模型的 220 种浏览器自动化工具</h3>
---
[](https://github.com/MathiasPaulenko/wavexis-mcp/actions/workflows/ci.yml)
[](https://pypi.org/project/wavexis-mcp/)
[](https://pypi.org/project/wavexis-mcp/)
[](https://github.com/MathiasPaulenko/wavexis-mcp/pkgs/container/wavexis-mcp)
[](https://github.com/MathiasPaulenko/wavexis-mcp/blob/main/LICENSE)
[](https://mathiaspaulenko.github.io/wavexis-mcp/)
> MCP 服务器，暴露 wavexis 浏览器自动化库给大语言模型。220 种工具，涵盖 13 个能力层级。不需要 Node.js，不需要下载 Chromium — 使用您现有的 Chrome/Edge 浏览器。100% Python 实现。
## 为什么选择 WaveXisMCP？
WaveXisMCP 封装了 [wavexis](https://github.com/MathiasPaulenko/wavexis) 浏览器自动化库，并将其暴露为 MCP 服务器。您不需要 Node.js、Playwright 或单独的 Chromium 下载 — WaveXisMCP 直接启动您现有的 Chrome 或 Edge 浏览器。
### 工作原理
```text
您（自然语言）
→ 大语言模型决定调用哪个工具
→ WaveXisMCP 接收工具调用
→ wavexis 库通过 CDP 或 BiDi 执行它
→ Chrome/Edge 执行操作
← 结果以 JSON 格式返回（文本、base64、文件路径）
← JSON 传递回大语言模型
← 大语言模型为你总结结果
```
大语言模型永远不会直接看到浏览器。它只看到工具定义（名称、描述、参数）和 JSON 响应。这意味着任何兼容 MCP 的大语言模型客户端都可以开箱即用 — 无需自定义集成。
### 核心概念
- **工具** — 单个浏览器操作（截图、评估、点击等）作为 MCP 工具暴露，任何大语言模型客户端都可以调用。
- **会话** — 持久的浏览器实例。打开会话，链接多个工具调用，完成后关闭。避免了每次操作启动浏览器的开销。
- **无状态模式** — 调用任何工具时带有 `url` 参数。浏览器启动，执行，自动关闭。
- **能力层级** — 13 个层级，从 `core`（72 种工具）到 `all`（220 种工具）。根据需要启用，使用 `--caps` 参数。
- **双后端** — CDP（Chromium 原生，通过 cdpwave）和 BiDi（W3C 跨浏览器，通过 bidiwave），每个会话可以选择。
- **结构化错误** — 每个错误都包含一个 `suggestion` 字段，告诉大语言模型下一步该怎么做，实现无需人工干预的自我纠正。
## 安装
```bash
pip install wavexis-mcp
```
使用 CDP 后端（Chromium）：
```bash
pip install "wavexis-mcp[cdp]"
```
或在不安装的情况下运行（推荐）：
```bash
uvx wavexis-mcp
```
## 要求
- **Python**：3.11、3.12 或 3.13
- **浏览器**：Google Chrome、Microsoft Edge 或任何 Chromium/Chrome-based 浏览器
- **BiDi 后端**（可选）：ChromeDriver/EdgeDriver，用于 W3C WebDriver BiDi
## 快速开始
将以下内容添加到您的 MCP 客户端配置中（Claude Desktop、Cursor、Windsurf、VS Code）：
```json
{
"mcpServers": {
"wavexis": {
"command": "uvx",
"args": ["wavexis-mcp", "--caps", "all"]
}
}
}
```
或使用 pip：
```json
{
"mcpServers": {
"wavexis": {
"command": "wavexis-mcp",
"args": ["--caps", "all"]
}
}
}
```
### 无状态模式（一键）
调用任何工具时带有 `url` 参数 — 浏览器启动，执行，自动关闭：
```text
wavexis_screenshot(url="https://example.com", full_page=true)
```
### 会话模式（多步）
打开会话，链接多个操作，完成后关闭：
```text
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` 与页面进行自然语言交互：
```text
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` 工具获取辅助功能快照，根据关键词评分将指令与元素匹配，并执行检测到的操作（点击、输入、填充、悬停）。无需外部大语言模型调用 — 纯启发式匹配。
## 能力层级
| 层级 | 参数 | 工具 | 关键特性 |
|------|------|-------|--------------|
| **核心** | 始终开启 | 72 | 会话、导航、截图、PDF、抓取、评估、DOM、输入、cookie、标签页、自然语言交互、iframe、影子 DOM、事件 |
| **网络** | `--caps=network` | 20 | 头部、用户代理、阻止、限制、缓存、HAR、拦截、模拟、修改请求/响应、请求体、HAR 重放、请求列表 |
| **存储** | `--caps=storage` | 18 | localStorage、sessionStorage、缓存存储、IndexedDB、状态保存/恢复 |
| **模拟** | `--caps=emulation` | 9 | 设备、视口、地理位置、时区、暗黑模式、语言、CPU、触摸、传感器 |
| **辅助功能** | `--caps=a11y` | 4 | 辅助功能树快照、节点遍历、axe-core 审计 |
| **交互** | `--caps=interactions` | 5 | 对话框、下载、权限 |
| **开发者工具** | `--caps=devtools` | 31 | 性能、CSS、调试、叠加层、控制台、安全、窗口管理、组合跟踪、注释截图 |
| **视觉** | `--caps=vision` | 7 | 基于坐标的鼠标（像素精确） |
| **视频** | `--caps=video` | 4 | 视频录制、章节、操作叠加层 |
| **测试** | `--caps=testing` | 6 | 断言、定位器生成 |
| **工作流** | `--caps=workflows` | 6 | 多操作 YAML、原始 CDP/BiDi、浏览器上下文 CRUD |
| **数据** | `--caps=data` | 7 | 代码生成、Lighthouse 审计、提取、WebSocket 拦截、爬取、视觉差异、核心网页指标 |
| **实验性** | `--caps=experimental` | 31 | 服务工作线程、动画、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 协议。直接与 Chrome/Edge 建立 WebSocket 连接。无需驱动程序。57 个 CDP 域。`pip install "wavexis-mcp[cdp]"`
- **BiDi**（bidiwave）— WebDriver BiDi 协议，W3C 跨浏览器（Firefox、Chrome）。需要 ChromeDriver/EdgeDriver。`pip install "wavexis-mcp[bidi]"`
每个会话可以选择：
```text
wavexis_session_open(backend="bidi")
```
## 多操作 YAML
通过传递 YAML 字符串链接多个操作：
```text
wavexis_multi_action(
config="""
actions:
- navigate: https://example.com
- screenshot:
full_page: true
- eval: document.title
- click: "#login"
- type:
selector: "#username"
text: admin@example.com
- 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：
```bash
# 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）
每个会话的令牌桶速率限制：
```bash
# 10 calls/sec, burst of 5
wavexis-mcp --rate-limit 10 --rate-burst 5
```
超出限制时，返回 `{"error": "rate_limited", "retry_after_ms": N}`。
## Docker
```bash
# 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 文档](https://mathiaspaulenko.github.io/wavexis-mcp/docker/)。
## 比较
| 特性 | Playwright MCP | **WaveXisMCP** |
|---------|---------------|----------------|
| 语言 | TypeScript | **Python** |
| 需要 Node.js | 是 | **否** |
| 下载 Chromium | 是（~200MB） | **否（使用现有的 Chrome/Edge）** |
| 安装大小 | ~200MB+ | **~5MB** |
| 总工具数 | ~70 | **220** |
| 能力层级 | 是（`--caps`） | **是（13 个层级）** |
| 双协议 | 否 | **CDP + BiDi** |
| 后端选择 | 否 | **是（每个会话）** |
| 原始 CDP/BiDi 访问 | 否 | **是（逃生口）** |
| 多操作 YAML | 否 | **是** |
| 视频录制 | 否 | **是** |
| Lighthouse 审计 | 否 | **是** |
| WebAuthn/蓝牙 | 否 | **是** |
| 自然语言交互 | 否 | **是（`wavexis_act`）** |
| MCP 资源和提示 | 否 | **是** |
| 速率限制 | 否 | **是** |
## 文档
完整的文档、API 参考和示例托管在 [mathiaspaulenko.github.io/wavexis-mcp](https://mathiaspaulenko.github.io/wavexis-mcp/)。
关键部分：
- [快速入门](https://mathiaspaulenko.github.io/wavexis-mcp/quickstart/)
- [架构](https://mathiaspaulenko.github.io/wavexis-mcp/architecture/)
- [配置](https://mathiaspaulenko.github.io/wavexis-mcp/configuration/)
- [Docker](https://mathiaspaulenko.github.io/wavexis-mcp/docker/)
- [HTTP 传输](https://mathiaspaulenko.github.io/wavexis-mcp/http-transport/)
- [速率限制](https://mathiaspaulenko.github.io/wavexis-mcp/rate-limiting/)
- [工具参考](https://mathiaspaulenko.github.io/wavexis-mcp/tools/core/)
- [示例](https://mathiaspaulenko.github.io/wavexis-mcp/examples/screenshot/)
## 错误处理
所有工具在失败时返回结构化错误 JSON。每个错误都包含一个 `suggestion` 字段，指导大语言模型进行下一步操作：
```json
{
"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."
}
```
这使得大语言模型可以自我纠正，无需人工干预 — 它读取建议并调用推荐的工具。
## 架构
WaveXisMCP 位于三层生态系统的顶部：
```text
WaveXisMCP（MCP 服务器，220 种工具）
└─ 封装 → wavexis（浏览器自动化库）
├─ cdpwave（CDP 后端，Chromium 原生）
└─ bidiwave（BiDi 后端，W3C 跨浏览器）
```
- **cdpwave** — 低级异步 Python 库，用于 Chrome DevTools 协议。直接与 Chrome/Edge 建立 WebSocket 连接。无需驱动程序二进制文件。
- **bidiwave** — 低级异步 Python 库，用于 WebDriver BiDi 协议（W3C 标准）。与 Firefox、Chrome 和 Edge 配合使用。
- **wavexis** — 高级浏览器自动化库，抽象了 cdpwave 和 bidiwave 背后统一的 `AbstractBackend` 接口。
- **WaveXisMCP** — MCP 服务器封装 wavexis。每个后端方法都作为带有 Pydantic v2 输入验证、JSON 响应和能力层级过滤的 MCP 工具公开。
详见 [架构文档](https://mathiaspaulenko.github.io/wavexis-mcp/architecture/) 以获取完整的系统设计、数据流图和 ADR。
## 开发
```bash
git clone https://github.com/MathiasPaulenko/wavexis-mcp.git
cd wavexis-mcp
pip install -e ".[dev]"
# 运行质量检查
ruff check wavexis_mcp tests
ruff format --check
mypy wavexis_mcp
python -m bandit -r wavexis_mcp
# 运行测试
pytest tests/unit -v
```
## 贡献
欢迎贡献。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取开发工作流、编码标准和拉取请求流程。对于安全问题，请参阅 [SECURITY.md](SECURITY.md)。
## 致谢
WaveXisMCP 建立在 [wavexis](https://github.com/MathiasPaulenko/wavexis) 浏览器自动化库和 [Model Context Protocol](https://modelcontextprotocol.io/) 之上。感谢开源 Python 和 MCP 社区提供的工具和标准，使该项目成为可能。
## 许可证
MIT
