Selenium MCP

Name: Selenium MCP
Author: gaforov

本地服务

npmjs.com浏览器自动化07 周前更新

文档代码仓库访问官网

关于 Selenium MCP

Selenium MCP 是面向 AI Agent 的 TypeScript 服务，通过 Selenium WebDriver 自动化真实浏览器。它将浏览器操作与页面快照、选择器提示、多会话管理和批量执行结合起来。

主要功能

01浏览器导航与交互工具
02包含稳定元素引用的页面快照
03按域名保存选择器提示
04并行浏览器会话
05批量执行多步操作
06断言与可选调用追踪

适用场景

01自动化浏览器工作流
02使用断言测试网页
03通过已保存的选择器重复任务
04调试浏览器工具调用过程

MCP 相关

向 MCP 客户端提供浏览器自动化工具，以及 `browser-status://current` 和 `accessibility://current` 资源。客户端可用这些工具管理会话、浏览页面、操作元素并截取屏幕截图。

#selenium #browser-automation #webdriver #testing #ai-agents #screenshots #selenium-mcp #selenium-mcp-server #selenium-webdriver

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "selenium-mcp-gaforov": {
      "command": "npx",
      "args": [
        "-y",
        "@gaforov/selenium-mcp"
      ]
    }
  }
}

启动命令npx -y @gaforov/selenium-mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@gaforov/selenium-mcp0.3.0stdio

工具

收录的工具列表 · 更新于 3 周前

参数	类型	必填	说明
browser	enum	否	启动的浏览器：chrome（默认）、firefox 或 edge。此浏览器必须已安装在此计算机上。chrome \| firefox \| edge
headless	boolean	否	以无可见窗口的方式运行（默认值为 false）。CI 或后台运行时使用 true；用户希望观看时使用 false。
browserArgs	array	否	浏览器的额外命令行标志，例如 ['--incognito'] 或 ['--lang=de']。默认无。
pageLoadTimeoutMs	integer	否	页面加载失败前允许的最长时间，单位为毫秒（默认值为 30000）。
scriptTimeoutMs	integer	否	异步脚本允许运行的最长时间，单位为毫秒（默认值为 30000）。
windowSize	object	否	初始窗口大小，例如 { width: 1440, height: 900 }。之后可使用 window 工具的 resize 操作进行更改。
windowSize.width	integer	是	窗口宽度，单位为像素（320-7680）。
windowSize.height	integer	是	窗口高度，单位为像素（240-4320）。

详细介绍

selenium-mcp

面向 AI Agent 的 Selenium MCP 服务——提供 41 个工具，用于自动化真实浏览器：导航、点击、输入、断言、屏幕截图、多会话管理、带稳定元素引用的页面快照、持久化选择器提示，以及批量多步执行。

使用 TypeScript、官方 MCP SDK 和 Selenium WebDriver 构建，具备严格的 zod 输入验证、显式等待，以及专为大模型 Agent 设计的结构化响应。

一键安装

0.3.0 新增内容

**新增工具：**用于下拉菜单的 select_option、用于滚动（包括无限滚动页面和可滚动面板）的 scroll、用于后退、前进和刷新的 history，以及用于在重定向后等待 URL 或标题的 wait_for_page。
**响应式测试：**现在可以使用 window 将视口调整到精确尺寸（例如 390x844 的手机屏幕），或将其最大化。
**帮助 AI Agent 更好地选择工具：**每个工具和参数现在都会说明其功能、返回内容，以及何时应改用类似工具。
**重大变更：**已移除重复的 open_url 和 wait_until_visible。请使用 navigate，并将 wait_for_element 的 visible: true 设为真。
**经过验证的发布版本：**每次发布前都会针对真实浏览器进行端到端测试，并通过 npm provenance 发布。

详情请参阅更新日志。

设置

Claude Code

claude mcp add selenium -- npx -y @gaforov/selenium-mcp@latest

Claude Desktop / Cursor / Windsurf / 其他 MCP 客户端

添加到客户端的 MCP 配置中（例如 claude_desktop_config.json 或 .cursor/mcp.json）：

{
  "mcpServers": {
    "selenium": {
      "command": "npx",
      "args": ["-y", "@gaforov/selenium-mcp@latest"]
    }
  }
}

VS Code

code --add-mcp '{"name":"selenium","command":"npx","args":["-y","@gaforov/selenium-mcp@latest"]}'

Goose

goose session --with-extension "npx -y @gaforov/selenium-mcp@latest"

IntelliJ IDEA / JetBrains IDE

Settings → Tools → AI Assistant → Model Context Protocol → Add，命令填写 npx，参数填写 -y @gaforov/selenium-mcp@latest。完整操作指南请见 docs/CLIENT_INTEGRATION.md。

从源代码构建

git clone https://github.com/gaforov/selenium-mcp.git
cd selenium-mcp
npm install
npm run build

然后将 MCP 客户端指向 node /absolute/path/to/selenium-mcp/dist/server.js。

## 示例用法

向你的 AI Agent 提问：

使用 selenium-mcp 打开 Chrome，访问 https://example.com，读取页面标题，截取屏幕截图，然后关闭浏览器。

Agent 会自行依次调用 start_browser → navigate → get_title → take_screenshot → stop_browser，无需编写脚本。

要求

Node.js 20+
已安装 Chrome、Firefox 或 Edge（Selenium Manager 会自动配置相应的驱动程序）

对比

大多数 Selenium MCP 服务都封装了 WebDriver 的基本命令。这个服务额外提供了让 Agent 可靠运行 的功能层：

能力	selenium-mcp	常见的 Selenium MCP 服务
提供稳定元素引用的页面快照（`capture_page`）	✅	少见
按域名持久保存选择器记忆（`selector_hint_*`）	✅	❌
并行多会话浏览	✅	少见
单次调用中批量执行多个步骤	✅	❌
内置测试断言	✅	部分支持
工具调用跟踪（NDJSON 审计日志）	✅	❌
严格的输入验证和结构化错误	✅	各不相同
为 AI Agent 描述每个工具及其参数（并由测试强制验证）	✅	各不相同
在 CI 中针对真实浏览器运行端到端测试	✅	部分支持

为什么选择 selenium-mcp

快照优先的工作流 — capture_page 会返回包含稳定元素引用的页面快照，Agent 可直接操作这些元素，无需脆弱地猜测选择器
选择器提示 — 按域名保存有效定位器，让重复的自动化操作随时间推移变得更快、更可靠
批量执行 — batch_execute 可在单次工具调用中运行受限的多步骤序列，减少往返调用
多会话 — 创建、选择、列出和销毁并行浏览器会话
便于 Agent 使用的错误信息 — 每个响应都经过 zod 结构化和验证，让 Agent 能够恢复，而不是陷入停滞
可选跟踪 — 以 NDJSON 格式记录每次工具调用，便于调试和审计

工具（41）

类别	工具
浏览器生命周期	`start_browser`、`stop_browser`、`session_create`、`session_select`、`session_list`、`session_destroy`
导航	`navigate`、`history`（后退/前进/刷新）、`wait_for_page`（URL/标题）、`get_current_url`、`get_title`
元素发现	`find_element`、`wait_for_element`、`capture_page`、`get_page_source`
交互	`click`、`retry_click`、`interact`（悬停/双击/右键单击）、`type`、`select_option`、`scroll`、`press_key`、`upload_file`
读取	`get_text`、`get_attribute`
断言	`assert_text`、`assert_visible`、`assert_attribute`
脚本执行	`execute_script`、`batch_execute`
选择器提示	`selector_hint_save`、`selector_hint_get`、`selector_hint_list`、`selector_hint_delete`
窗口和上下文	`window`（标签页、窗口、调整大小/最大化）、`frame`、`alert`
Cookie	`add_cookie`、`get_cookies`、`delete_cookie`
截取	`take_screenshot`

完整的参数文档：docs/TOOL_REFERENCE.md

MCP 资源

browser-status://current — 实时浏览器/会话状态
accessibility://current — 当前页面的无障碍快照

可选跟踪

启用所有工具调用的轻量级 NDJSON 跟踪：

SELENIUM_MCP_TRACE=true
SELENIUM_MCP_TRACE_PATH=./logs/selenium-mcp-trace.ndjson

如果省略 SELENIUM_MCP_TRACE_PATH，默认路径为 logs/selenium-mcp-trace.ndjson。

文档

贡献

欢迎贡献，包括错误报告、功能请求和拉取请求。请参阅 CONTRIBUTING.md 以开始参与。

npm run typecheck
npm run build
npm test

许可证

MIT。请参阅 LICENSE。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。