内容
# seleniumboot-mcp
Python **模型上下文协议（MCP）** 服务器，用于 Selenium WebDriver 自动化。
让 Claude 或 GitHub Copilot 控制真实浏览器 — 导航页面，与元素交互，
运行断言，并从记录的会话中生成可运行的 **Java TestNG / JUnit 5 / Cucumber / pytest** 测试代码。
85 种工具。无需 ChromeDriver 设置。浏览器在首次使用时自动启动。
[](https://pypi.org/project/seleniumboot-mcp/)
[](https://pypi.org/project/seleniumboot-mcp/)
[](LICENSE)
[](https://marketplace.visualstudio.com/items?itemName=seleniumboot.selenium-boot-mcp)
[](https://plugins.jetbrains.com/plugin/32516)
[](https://plugins.jetbrains.com/plugin/32516)
---
## 演示
▶ [在 YouTube 上观看演示](https://youtu.be/54LoY2HNLrs)
---
## 安装
```bash
pip install seleniumboot-mcp
```
> 需要 Python 3.10+ 和 Chrome。不需要单独的 ChromeDriver — Selenium Manager 自动处理。
---
## 设置
### VS Code — 市场扩展（最简单）
在 VS Code 市场中安装 **[Selenium Boot MCP](https://marketplace.visualstudio.com/items?itemName=seleniumboot.selenium-boot-mcp)**。
扩展程序自动：
- 将 MCP 服务器注册到 **GitHub Copilot**（无需配置文件）
- 在您的项目中创建 `.mcp.json`，以便 **Claude Code** 在下次打开时检测到它
- 如果缺少 Python 包，则提示 `pip install seleniumboot-mcp`
当 Claude Code 询问 *"允许 MCP 服务器 seleniumboot？"* 时 — 点击 **允许**。
### JetBrains IDE — 市场插件
在 **设置 → 插件 → 市场**（搜索“Selenium Boot MCP”）或插件页面中安装 **[Selenium Boot MCP](https://plugins.jetbrains.com/plugin/32516)**。
插件将 MCP 服务器注册到 **JetBrains AI 助手**，并提示安装 `seleniumboot-mcp` Python 包（如果缺失）。使用 **工具 → Selenium Boot MCP** 安装/升级、注册或检查状态。
### VS Code — 手动
在项目根目录中添加 `.vscode/mcp.json`（适用于 GitHub Copilot）：
```json
{
"servers": {
"selenium": {
"type": "stdio",
"command": "seleniumboot-mcp"
}
}
}
```
对于 Claude Code，在项目根目录中添加 `.mcp.json`：
```json
{
"mcpServers": {
"seleniumboot": {
"command": "seleniumboot-mcp",
"args": []
}
}
}
```
在 VS Code 中打开项目 → Claude Code 将提示批准服务器 → 完成。
### Claude 桌面版
编辑 Claude 桌面版配置：
- **Windows:** `%APPDATA%\claude-desktop\config.json`
- **macOS:** `~/.config/claude-desktop/config.json`
```json
{
"mcpServers": {
"selenium": {
"command": "seleniumboot-mcp"
}
}
}
```
重启 Claude 桌面版。
---
## 使用方法
服务器运行后，像平常一样与 Claude 交谈 — 无需 `start_browser` 调用，Chrome 在首次使用时自动启动：
```
前往 https://myapp.com 并用 admin/password 填充登录表单，然后点击登录
```
```
断言仪表板标题可见
```
```
为我们刚刚执行的所有操作生成一个 Java TestNG 测试类
```
```
为登录流程生成一个 Gherkin 特性文件和步骤定义
```
Claude 控制真实浏览器，记录每个操作，并在请求时生成完整的测试代码，以便粘贴到您的 Maven 或 Gradle 项目中。
---
## 工具（共 84 个）
### 浏览器
| 工具 | 描述 |
|---|---|
| `start_browser` | 可选 — Chrome 在首次使用时自动启动。使用此工具选择 Firefox，启用无头模式或设置窗口大小 |
| `navigate` | 前往 URL |
| `take_screenshot` | 捕获页面为内联图像 |
| `get_page_title` | 返回页面标题 |
| `get_current_url` | 返回当前 URL |
| `get_page_source` | 返回完整的 HTML 源代码 |
| `execute_script` | 运行 JavaScript |
| `go_back` / `go_forward` | 浏览器历史记录 |
| `refresh` | 重新加载页面 |
| `switch_to_window` | 通过索引切换到其他标签页 |
| `open_new_tab` | 打开新的浏览器标签页，可选地在 URL 处 |
| `close_current_tab` | 关闭当前标签页并切换到前一个标签页 |
| `list_windows` | 列出所有打开的标签页及其索引、标题和 URL |
| `close_browser` | 退出浏览器 |
| `scroll_to_top` | 滚动页面到顶部 |
| `scroll_to_bottom` | 滚动页面到底部 |
| `scroll_by` | 按 x/y 像素滚动页面 |
| `emulate_device` | 通过 CDP 模拟移动设备（iPhone、iPad、Pixel、Galaxy） |
| `get_console_logs` | 获取浏览器控制台错误/警告/信息（Chrome） |
| `get_cookies` / `set_cookie` | 读取或写入 cookie |
| `delete_cookie` / `delete_all_cookies` | 删除 cookie |
| `get_local_storage` / `set_local_storage` | 读取或写入 localStorage |
| `get_session_storage` / `set_session_storage` | 读取或写入 sessionStorage |
| `wait_for_network_idle` | 等待 XHR/fetch 流量平静 — 对 SPA 至关重要 |
| `inspect_page` | 发现所有输入、按钮、选择、链接及其最佳 CSS 选择器 |
| `get_network_logs` | 捕获的 XHR/fetch 请求 — 方法、URL、状态、时间 |
| `mock_response` | 用 canned 响应伪造 fetch/XHR 的 URL 模式 |
| `clear_mock_responses` | 删除所有活动模拟规则 |
| `compare_screenshot` | 与保存的基准进行像素差异比较 — 视觉回归 |
| `check_accessibility` | 内置的 WCAG 审计 — 替代文本、标签、标题、键盘访问 |
### 元素
| 工具 | 描述 |
|---|---|
| `find_element` | 查找元素，返回标签/文本/状态 |
| `find_elements` | 查找所有匹配的元素 |
| `click` | 显式等待点击 |
| `type_text` | 清除 + 输入到输入框 |
| `get_text` | 获取可见文本 |
| `get_attribute` | 获取任何属性值 |
| `select_option` | 通过文本、值或索引从 `<select>` 中选择 |
| `hover` | 鼠标悬停 |
| `double_click` | 双击 |
| `right_click` | 上下文菜单点击 |
| `drag_and_drop` | 拖动源 → 目标 |
| `is_displayed` | 检查可见性 |
| `is_enabled` | 检查启用状态 |
| `wait_for_element` | 等待：可见 / 可点击 / 存在 / 不可见 |
| `scroll_to_element` | 滚动元素到视图中 |
| `clear_field` | 清除输入字段 |
| `send_keys` | 发送特殊键（Tab、Enter、Escape、Ctrl+A、F5、...） |
| `upload_file` | 通过 `<input type="file">` 上传文件 |
| `accept_alert` / `dismiss_alert` | 处理 JS 警报/确认对话框 |
| `get_alert_text` | 读取警报中的消息 |
| `type_in_alert` | 输入到 JS 提示并确认 |
| `switch_to_frame` | 通过索引、名称或选择器聚焦到 iframe |
| `switch_to_default_content` | 从框架返回到主页面 |
| `find_shadow_element` | 在 shadow DOM 中查找元素 |
| `get_table_data` | 提取 HTML 表格为格式化文本网格 |
| `fill_form` | 一次填充多个字段 — 自动检测输入/选择/复选框/单选按钮 |
| `get_healed_locators` | 查看会话的所有自愈选择器映射 |
| `clear_healed_locators` | 重置自愈缓存 |
### 断言
| 工具 | 描述 |
|---|---|
| `assert_title` | 页面标题等于/包含 |
| `assert_url` | URL 等于/包含 |
| `assert_text` | 元素文本等于/包含 |
| `assert_element_visible` | 元素可见 |
| `assert_element_not_visible` | 元素隐藏或不存在 |
| `assert_attribute` | 元素属性具有预期值 |
| `assert_page_contains` | 页面正文包含字符串 |
| `assert_element_count` | 匹配元素的数量等于预期 |
### 代码生成
| 工具 | 描述 |
|---|---|
| `generate_java_testng` | 从会话生成 Java TestNG 测试类 |
| `generate_java_junit5` | 从会话生成 Java JUnit 5 测试类 |
| `generate_java_page_object` | 从会话生成 Java 页面对象类 + 测试类 |
| `generate_gherkin` | 从会话生成 Gherkin `.feature` 文件 + Java 步骤定义 |
| `generate_python_test` | 从会话生成 pytest 类 |
| `generate_csharp_nunit` | 从会话生成 C# NUnit + Selenium 测试类 |
| `generate_github_actions` | 从会话生成 GitHub Actions CI 工作流 YAML（Maven / Gradle / pytest） |
| `generate_jenkins_pipeline` | 从会话生成声明性 Jenkinsfile（Maven / Gradle / pytest） |
| `generate_gitlab_ci` | 从会话生成 GitLab CI `.gitlab-ci.yml` 管道（Maven / Gradle / pytest） |
| `generate_playwright_hints` | 从会话生成等效的 Playwright TypeScript 代码 |
| `get_session_log` | 查看记录的操作 |
| `clear_session_log` | 重置会话记录 |
---
## 代码生成示例
### Java TestNG
```
前往 https://myapp.com/login，输入 admin/password，点击登录
→ 生成一个 Java TestNG 测试
```
```java
public class LoginTest {
@BeforeMethod public void setUp() { driver = new ChromeDriver(); ... }
@AfterMethod public void tearDown() { driver.quit(); }
@Test
public void recordedFlowTest() {
driver.get("https://myapp.com/login");
WebElement f = wait.until(visibilityOf(By.cssSelector("#username")));
f.clear(); f.sendKeys("admin");
wait.until(elementToBeClickable(By.cssSelector("button[type='submit']"))).click();
}
}
```
### 页面对象模型
```
为登录页面生成一个 Java 页面对象
```
```java
// LoginPage.java
public class LoginPage {
private final By usernameField = By.cssSelector("#username");
private final By submitButton = By.cssSelector("button[type='submit']");
public LoginPage enterUsernameField(String text) { ... return this; }
public LoginPage clickSubmitButton() { ... return this; }
}
// LoginTest.java
public class LoginTest {
@Test public void recordedFlowTest() {
driver.get("https://myapp.com/login");
page.enterUsernameField("admin").clickSubmitButton();
}
}
```
### Cucumber / Gherkin
```
为登录流程生成一个 Gherkin 特性文件和步骤定义
```
```gherkin
Feature: 登录
Scenario: 用户使用有效凭证登录
Given 我导航到 "https://myapp.com/login"
And 我在用户名字段中输入 "admin"
And 我在密码字段中输入 "password"
And 我点击提交按钮
```
```java
// LoginSteps.java
public class LoginSteps {
@Given("我导航到 {string}")
public void iNavigateTo(String url) { driver.get(url); }
@And("我在用户名字段中输入 {string}")
public void iEnterInUsernameField(String text) { ... el.sendKeys(text); }
@And("我点击提交按钮")
public void iClickTheSubmitButton() { wait.until(...).click(); }
}
```
---
## 自愈定位器
当选择器无法找到元素时，seleniumboot-mcp 会自动尝试其他策略，然后再放弃：
| 主要选择器 | 尝试的替代方案 |
|---|---|
| `#my-id` （CSS） | `by=id "my-id"`， `[id='my-id']` |
| `.my-class` （CSS） | `by=class "my-class"`， `[class*='my-class']` |
| `input[type='email']` （CSS） | `//input[@type='email']` （XPath） |
| `//button[@id='ok']` （XPath） | `button[id='ok']` （CSS）， `by=id "ok"` |
| `"A, B"` 逗号列表 | 尝试 A，然后尝试 B |
成功的备用方案会被 **缓存**，因此修复后的选择器会被自动重用。使用 `get_healed_locators` 检查缓存并更新测试代码，并使用 `clear_healed_locators` 开始新的缓存。
---
## 链接
- **GitHub:** [github.com/seleniumboot/selenium-mcp](https://github.com/seleniumboot/selenium-mcp)
- **PyPI:** [pypi.org/project/seleniumboot-mcp](https://pypi.org/project/seleniumboot-mcp/)
- **VS Code 市场:** [marketplace.visualstudio.com](https://marketplace.visualstudio.com/items?itemName=seleniumboot.selenium-boot-mcp)
---
## 路线图
- [x] Java TestNG / JUnit 5 / Python pytest 代码生成
- [x] 以 `ImageContent` 形式返回截图（在 Claude 中内联渲染）
- [x] 完整的会话记录 — 悬停、双击、右键单击、滚动、选择选项
- [x] Java 和 Python 模板中的悬停、拖放、选择、滚动的代码生成
- [x] 首次使用时自动启动浏览器（无需显式 `start_browser` 调用）
- [x] 页面对象模型生成（`generate_java_page_object`）
- [x] Cucumber / Gherkin 步骤生成（`generate_gherkin`）
- [x] 自愈定位器 — 当选择器损坏时的自动备用方案
- [x] 警报/对话框处理、iframe 切换、shadow DOM、表格提取
- [x] Cookie、localStorage、sessionStorage 管理
- [x] 通过 Chrome DevTools 协议模拟移动设备
- [x] 发送特殊键（Tab、Enter、F-keys、Ctrl+A、...）
- [x] 通过 `<input type="file">` 上传文件
- [x] 浏览器控制台日志捕获
- [x] 多标签页管理（打开、关闭、列表）
- [x] 页面滚动（顶部、底部、按像素）
- [x] C# NUnit + Selenium 代码生成
- [x] GitHub Actions CI 工作流生成器（Maven / Gradle / pytest）
- [x] Playwright TypeScript 迁移提示
- [x] Jenkins / GitLab CI 的 CI/CD 配置
---
## 许可证
MIT
