内容
# mcp-server-webdriver
使用 **Selenium WebDriver** （Firefox + geckodriver）控制真实网页浏览器的MCP服务器。
由 [FastMCP](https://gofastmcp.com) 构建。
---
## 功能描述
该服务器消除了浏览器和AI助手之间的复制粘贴循环。
不再需要打开开发者工具，复制错误信息，粘贴到聊天中，然后重复，
助手直接打开浏览器，导航，捕获错误和截图，
直接诊断问题。
```
你： "为什么/cart页面的结账按钮坏了？"
AI： browser_open → browser_navigate("/cart")
→ devtools_report # JavaScript错误？网络故障？
→ browser_screenshot # 看起来是什么样子？
→ devtools_computed_css("button#checkout") # 隐藏？z-index错误？
→ "按钮有pointer-events: none — 被.disabled类覆盖，
当/cart.js加载失败（/static/cart.js 404）时应用。"
```
---
## 需求
| 依赖 | 版本 |
|---|---|
| Python | ≥ 3.11 |
| [FastMCP](https://pypi.org/project/fastmcp/) | ≥ 2.10 |
| [selenium](https://pypi.org/project/selenium/) | ≥ 4.0 |
| Firefox | 任意近期版本 |
| [geckodriver](https://github.com/mozilla/geckodriver) | ≥ 0.34 |
---
## 安装
### 推荐 — 使用VitexSoftware仓库的Debian软件包
```bash
sudo curl -fsSL http://repo.vitexsoftware.com/KEY.gpg -o /usr/share/keyrings/vitexsoftware-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/vitexsoftware-archive-keyring.gpg] http://repo.vitexsoftware.com trixie main" \
| sudo tee /etc/apt/sources.list.d/vitexsoftware.list
sudo apt update
sudo apt install python3-mcp-server-webdriver
```
这一步安装了`gecko-driver`、`python3-selenium`、`python3-fastmcp`和`mcp-server-webdriver`。
### 替代 — 使用系统包管理器
```bash
# Debian/Ubuntu（官方仓库 — 可能有较旧的geckodriver）：
sudo apt install firefox-geckodriver
# macOS：
brew install geckodriver
# Rust / cargo（从源代码构建）：
cargo install geckodriver
```
然后安装Python依赖：
```bash
pip install fastmcp selenium
```
### 备用 — 使用webdriver-manager（自动下载）
```bash
pip install fastmcp selenium webdriver-manager
# geckodriver在第一次browser_open调用时自动下载
```
---
## 使用
```
mcp-server-webdriver [选项]
选项
-P <配置文件> 使用指定的Firefox配置文件启动
--profile <路径> 使用指定路径的Firefox配置文件启动
-h, --help 显示帮助信息并退出
```
服务器通过stdin/stdout与MCP客户端通信，
由MCP客户端自动启动 — 而不是手动启动。
---
## 用例
### 调试损坏的页面
询问： *"为什么/dashboard页面显示空白屏幕？"*
助手将：
1. `browser_open` — 打开无头Firefox
2. `browser_navigate` — 访问/dashboard
3. `devtools_report` — 获取JavaScript错误、控制台输出和失败的网络资源
4. `browser_screenshot` — 查看页面的实际外观
5. 从综合证据中解释根本原因
`devtools_report`是主要的诊断工具 —
相当于在开发者工具中打开控制台和网络选项卡并同时阅读它们。
---
### 诊断CSS/布局问题
询问： *"移动设备上侧边栏与内容区域重叠。为什么？"*
1. `browser_open` — 打开页面
2. `browser_screenshot` — 捕获损坏的布局
3. `devtools_computed_css(".sidebar")` — 检查`position`、`width`、`z-index`、`overflow`
4. `devtools_css_variables("--")` — 验证设计令牌是否正确加载
5. `devtools_network_failed` — 检查是否有样式表加载失败
---
### 自动化登录流程
询问： *"使用用户=admin，密码=secret登录/login页面，并截图/dashboard页面。"*
1. `browser_open` — 启动浏览器
2. `browser_navigate` — 访问/login页面
3. `browser_fill("#username", "admin")` — 输入用户名
4. `browser_fill("#password", "secret")` — 输入密码
5. `browser_press_key("enter")` — 提交表单
6. `browser_wait("#dashboard", condition="visible")` — 等待重定向
7. `browser_screenshot` — 捕获结果
---
### 注入会话cookie以跳过登录
询问： *"使用我的现有会话令牌检查管理员面板。"*
1. `browser_open` — 启动浏览器
2. `browser_navigate` — 访问应用程序的根目录，使cookie域名匹配
3. `browser_set_cookie("session", "<token>")` — 注入身份验证cookie
4. `browser_navigate` — 现在导航到受保护的页面
5. `browser_screenshot` — 确认访问
---
### 枚举页面内容
询问： *"列出首页上的所有导航链接。"*
1. `browser_open` + `browser_navigate` — 打开页面
2. `browser_find_elements("nav a")` — 获取所有链接及其文本、href和可见性
3. 返回结构化列表
---
### 与悬停菜单交互
询问： *"点击产品下拉菜单中的第三个项目。"*
1. `browser_hover(".nav-products")` — 触发:hover状态以显示下拉菜单
2. `browser_wait(".dropdown-menu", condition="visible")` — 等待动画
3. `browser_find_elements(".dropdown-menu a")` — 列出项目
4. `browser_click(".dropdown-menu a:nth-child(3)")` — 点击正确的项目
---
### 测试多步骤表单
询问： *"填写注册表单并提交。"*
1. `browser_fill("#first-name", "Alice")`
2. `browser_fill("#last-name", "Smith")`
3. `browser_fill("#email", "alice@example.com")`
4. `browser_select("#country", "Czech Republic")`
5. `browser_press_key("tab")` — 移动焦点到下一个字段
6. `browser_click("button[type=submit"]")`
7. `browser_wait(".success-message", condition="visible")`
8. `devtools_report` — 检查提交过程中是否有JavaScript错误或API调用失败
---
### 处理JavaScript对话框
询问： *"点击删除按钮并确认对话框。"*
1. `browser_click("#delete-btn")`
2. `browser_accept_dialog` — 在confirm("Are you sure?")上点击OK
3. `browser_wait(".deleted-notice", condition="present")`
---
### 滚动和捕获长页面
询问： *"截图页脚。"*
1. `browser_open` + `browser_navigate`
2. `browser_scroll("footer")` — 将页脚元素滚动到视图中
3. `browser_screenshot("footer")` — 仅捕获页脚元素
或者，通过偏移量滚动以触发延迟加载的内容：
1. `browser_scroll(by=True, y=1000)` — 向下滚动1000像素
2. `browser_wait(".lazy-section", condition="visible")` — 等待延迟内容
3. `browser_screenshot` — 捕获现在加载的内容
---
### 使用真实的Firefox配置文件（保持登录状态）
使用已保存会话的命名配置文件配置服务器：
```json
{
"mcpServers": {
"webdriver": {
"command": "mcp-server-webdriver",
"args": ["-P", "work"]
}
}
}
```
浏览器使用现有的cookie、保存的密码和扩展程序启动。
询问： *"检查我的GitHub通知。"* — 无需登录步骤。
---
### 审计网络性能
询问： *"哪些资源在/shop页面加载最慢？"*
1. `browser_open` + `browser_navigate("/shop")`
2. `devtools_network_all(slow_ms=500, limit=20)` — 请求超过500毫秒，限制为20条记录
3. 报告最慢的资产及其URL、类型和持续时间
---
## 可用工具
### 会话管理
| 工具 | 描述 |
|---|---|
| `browser_open` | 打开Firefox（可选URL，默认为about:blank）；接受`width`、`height`、`user_agent`用于移动设备模拟 |
| `browser_close` | 退出浏览器会话 |
| `browser_status` | 会话状态、geckodriver版本、BiDi状态、当前视口大小、缓冲区计数 |
| `browser_set_viewport` | 在会话期间调整视口大小（例如iPhone 14的390×844） |
### 导航
| 工具 | 描述 |
|---|---|
| `browser_navigate` | 导航到URL（裸主机名获取`https://`） |
| `browser_back` | 返回历史记录 |
| `browser_forward` | 前进历史记录 |
| `browser_refresh` | 重新加载当前页面 |
### 页面检查
| 工具 | 描述 |
|---|---|
| `browser_screenshot` | 全页或元素PNG截图 |
| `browser_get_title` | 当前页面`<title>` |
| `browser_get_url` | 当前URL |
| `browser_get_source` | 原始HTML源代码 |
| `browser_get_text` | 可见文本（整个页面或CSS选择器） |
| `browser_get_attribute` | 元素上HTML属性的值 |
| `browser_find_elements` | 列出所有匹配CSS选择器的元素 |
### 交互
| 工具 | 描述 |
|---|---|
| `browser_click` | 点击元素（CSS选择器） |
| `browser_fill` | 在输入字段中输入文本（默认为清除） |
| `browser_select` | 在`<select>`下拉菜单中选择`<option>` |
| `browser_execute_js` | 运行JavaScript — 返回JSON |
| `browser_wait` | 等待：`visible` / `clickable` / `present` / `text:<str>` |
| `browser_scroll` | 滚动到坐标、偏移量或元素视图中 |
| `browser_press_key` | 发送`enter` / `tab` / `escape` / 箭头键 / F键 |
| `browser_hover` | 将鼠标悬停在元素上（:hover状态、提示信息、下拉菜单） |
| `browser_switch_frame` | 切换到`<iframe>`或返回主文档 |
### 对话框和cookie
| 工具 | 描述 |
|---|---|
| `browser_accept_dialog` | 接受JavaScript `alert()` / `confirm()` / `prompt()` |
| `browser_dismiss_dialog` | 取消JavaScript `confirm()` / `prompt()` |
| `browser_get_cookies` | 读取当前页面的所有cookie |
| `browser_set_cookie` | 注入cookie（身份验证令牌、会话ID） |
### 开发者工具（需要BiDi — Firefox + geckodriver ≥ 0.34）
| 工具 | 描述 |
|---|---|
| `devtools_report` | **主要诊断工具** — JavaScript错误 + 控制台 + 失败/慢速网络 |
| `devtools_js_errors` | 仅JavaScript异常 |
| `devtools_console` | 控制台输出（log / warn / error / info / debug） |
| `devtools_network_failed` | 失败的资源（4xx、5xx、DNS错误） |
| `devtools_network_all` | 所有网络请求（支持`limit=`和过滤器） |
| `devtools_clear` | 清除缓冲的开发者工具数据（在导航前使用） |
| `devtools_enable_bidi` | 附加BiDi监听器到正在运行的会话 |
| `devtools_computed_css` | 元素的计算CSS属性 |
| `devtools_element_info` | 边界框、可见性、属性、aria、outerHTML |
| `devtools_css_variables` | CSS自定义属性（--var）的作用域 |
---
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `GECKODRIVER_PATH` | _(未设置)_ | geckodriver二进制文件的绝对路径（优先级最高） |
| `GECKODRIVER_AUTO_INSTALL` | `true` | 设置为`false`以禁用webdriver-manager备用方案 |
| `FIREFOX_BINARY` | _(未设置)_ | 自定义Firefox可执行文件的路径 |
| `FIREFOX_PROFILE` | _(未设置)_ | 命名的Firefox配置文件 — 与`-P`相同 |
| `FIREFOX_PROFILE_DIR` | _(未设置)_ | 配置文件目录路径 — 与`--profile`相同 |
---
## geckodriver解析顺序
| # | 源 | 配置方式 |
|---|---|---|
| 1 | `GECKODRIVER_PATH`环境变量 | 二进制文件的绝对路径 |
| 2 | **系统PATH**（默认） | `apt install gecko-driver`来自repo.vitexsoftware.com |
| 3 | webdriver-manager自动下载 | 备用方案；禁用`GECKODRIVER_AUTO_INSTALL=false` |
---
## MCP客户端配置
最小配置：
```json
{
"mcpServers": {
"webdriver": {
"command": "mcp-server-webdriver"
}
}
}
```
使用命名的Firefox配置文件（保持登录状态，使用保存的密码）：
```json
{
"mcpServers": {
"webdriver": {
"command": "mcp-server-webdriver",
"args": ["-P", "work"]
}
}
}
```
使用配置文件目录和显式geckodriver路径：
```json
{
"mcpServers": {
"webdriver": {
"command": "mcp-server-webdriver",
"args": ["--profile", "/home/user/.mozilla/firefox/abc123.dev"],
"env": {
"GECKODRIVER_PATH": "/usr/bin/geckodriver"
}
}
}
}
```
---
## 运行测试
```bash
# 仅单元测试（无需浏览器）：
pytest tests/ -m "not integration"
# 包括浏览器集成的所有测试：
pytest tests/
```
---
## 相关MCP服务器由VitexSoftware提供
| 服务器 | 描述 |
|---|---|
| [abraflexi-mcp-server](https://github.com/VitexSoftware/abraflexi-mcp-server) | AbraFlexi会计/ERP集成 — 发票、联系人、产品、银行交易 |
| [mastodon-mcp-server](https://github.com/VitexSoftware/mastodon-mcp-server) | Mastodon集成 — 时间线、发帖、账户管理、搜索 |
| [semaphore-mcp-server](https://github.com/VitexSoftware/semaphore-mcp-server) | Semaphore UI集成 — 管理Ansible、Terraform和其他自动化工作流 |
---
## 许可证
MIT
