MCP Selenium

一个全面的Model Context Protocol (MCP)服务器实现，用于Selenium WebDriver，通过标准化的MCP客户端（如Claude Desktop和其他兼容MCP的应用程序）实现高级浏览器自动化。

这使得AI助手能够使用80多种自动化工具来编程控制网络浏览器。

<img style="display: inline-block;" src="https://img.shields.io/npm/v/@sirblob/mcp-selenium"> <img style="display: inline-block;" src="https://img.shields.io/npm/dt/@sirblob/mcp-selenium" > <img style="display: inline-block;" src="https://img.shields.io/github/issues/SirBlobby/mcp-selenium" >

安装

使用npm安装包：

npm install @sirblob/mcp-selenium

使用pnpm安装包：

pnpm install @sirblob/mcp-selenium

使用方法

添加到您的MCP客户端配置中：

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

支持的浏览器

• Chrome - 包括无头模式在内的全部功能支持
• Firefox - 包括无头模式在内的全部功能支持
• Edge - 包括无头模式在内的全部功能支持
• Safari - 基本功能支持（选项有限）

可用工具

浏览器管理

• start_browser - 启动浏览器（Chrome、Firefox、Edge或Safari），可选配置
• navigate - 导航到指定URL
• close_session - 关闭当前浏览器会话
• get_browser_status - 获取当前浏览器会话的状态

元素查找与交互

• find_element - 使用各种定位策略查找元素
• click_element - 点击元素
• send_keys - 向元素发送文本输入（打字）
• get_element_text - 获取元素的文本内容
• get_element_source - 获取元素及其所有子元素的HTML源代码
• upload_file - 使用文件输入元素上传文件
• find_elements_by_xpath - 使用XPath查找多个元素
• scroll_to_element - 滚动以使元素可见
• highlight_element - 调试时高亮显示元素
• find_parent_element - 查找给定元素的父元素
• find_sibling_element - 查找给定元素的兄弟元素

下拉列表元素工具

• select_option_by_text - 根据可见文本选择下拉列表中的选项
• select_option_by_value - 根据值属性选择下拉列表中的选项
• select_option_by_index - 根据索引选择下拉列表中的选项
• get_select_options - 获取下拉列表中的所有可用选项
• get_selected_option - 获取下拉列表中当前选定的选项

表格元素工具

• get_table_data - 提取表格元素中的所有数据
• get_table_cell - 根据行和列获取特定单元格的内容
• click_table_cell - 根据行和列点击特定单元格
• get_table_row_count - 获取表格中的行数
• get_table_column_count - 获取表格中的列数
• find_table_row_by_text - 查找包含特定文本的表格行

列表元素工具

• get_list_items - 获取列表元素（ul或ol）中的所有项目
• get_list_item - 根据索引获取特定列表项
• click_list_item - 根据索引点击特定列表项
• click_list_item_by_text - 点击包含特定文本的列表项
• find_list_item_by_text - 查找包含特定文本的列表项的索引
• get_list_item_count - 获取列表中的项目数量
• get_nested_lists - 获取列表内嵌套列表的信息
• filter_list_items - 根据文本标准过滤列表项

元素状态和属性

• get_element_attribute - 获取元素的属性值
• get_element_css_property - 获取元素的CSS属性值
• is_element_displayed - 检查元素是否可见
• is_element_enabled - 检查元素是否启用/可交互
• is_element_selected - 检查元素是否被选中（复选框、单选按钮）

鼠标和键盘交互

• hover - 将鼠标移动到元素上悬停
• hover_element - 元素交互的另一种悬停命令
• drag_and_drop - 将元素拖放到另一个位置
• double_click - 双击元素
• right_click - 右键点击元素（上下文菜单）
• send_key_combination - 发送键盘组合（Ctrl+C, Alt+Tab等）
• press_key - 模拟按下单一键盘键

页面操作

• take_screenshot - 捕获当前页面的截图，并将其保存到当前目录，带有时间戳
• get_page_title - 获取当前页面标题
• get_title - 获取当前页面标题的另一种方法
• get_current_url - 获取当前页面的URL
• get_page_source - 获取页面的完整HTML源代码
• page_source - 获取页面完整HTML源代码的另一种方法
• refresh_page - 刷新当前页面
• go_back - 在浏览器历史记录中后退
• go_forward - 在浏览器历史记录中前进

JavaScript执行

• execute_javascript - 在浏览器中执行JavaScript代码
• execute_async_javascript - 执行异步JavaScript并支持回调

滚动

• scroll_to_element - 滚动以使元素可见
• scroll_element_into_view - 将元素滚动到视图中的另一种方法
• scroll_by_pixels - 按指定像素数滚动
• scroll_to_coordinates - 滚动到页面上的特定坐标
• scroll_to_top - 滚动到页面顶部
• scroll_to_bottom - 滚动到页面底部

窗口管理

• get_window_size - 获取当前窗口尺寸
• set_window_size - 设置窗口大小
• maximize_window - 最大化浏览器窗口
• get_window_handles - 获取所有打开的窗口句柄
• switch_to_window - 通过句柄切换到特定窗口
• switch_to_window_by_title - 通过标题切换到窗口/标签页
• switch_to_window_by_url - 通过URL切换到窗口/标签页
• close_window - 关闭当前窗口
• switch_to_frame - 通过ID或名称切换到框架
• switch_to_default_content - 切换回主文档

Cookie管理

• get_cookies - 获取当前域的所有cookie
• add_cookie - 添加新的cookie
• delete_cookie - 删除特定的cookie
• delete_all_cookies - 删除所有cookie

XPath工具

• evaluate_xpath - 评估XPath表达式并返回结果
• count_elements_by_xpath - 计算匹配XPath表达式的元素数量
• get_xpath_text_content - 获取匹配XPath的元素的文本内容
• get_element_source_by_xpath - 获取匹配XPath的元素的HTML源代码
• get_element_xpath - 获取元素的XPath
• get_elements_xpath - 获取多个元素的XPath表达式
• get_element_attribute_by_xpath - 使用XPath从元素获取属性值
• find_element_by_xpath_attribute - 根据XPath和属性值查找元素
• find_element_by_xpath_index - 根据XPath在特定索引处查找元素
• click_element_by_xpath_text - 点击包含特定文本的XPath找到的元素

高级元素操作

元素状态和属性

• get_element_attribute - 获取元素的属性值
• get_element_css_property - 获取元素的CSS属性值
• is_element_displayed - 检查元素是否可见
• is_element_enabled - 检查元素是否启用/可交互
• is_element_selected - 检查元素是否被选中（复选框、单选按钮）

配置参数

浏览器选项

通过可选参数配置浏览器行为：

{
  "headless": false,
  "arguments": ["--window-size=1920,1080", "--disable-web-security", "--disable-dev-shm-usage"]
}

常见浏览器参数：

• --headless=new - 在无头模式下运行（Chrome/Edge）
• --window-size=width,height - 设置初始窗口大小
• --disable-web-security - 禁用CORS限制
• --disable-dev-shm-usage - 解决资源问题
• --no-sandbox - 禁用沙箱（容器化环境中有用）
• --disable-gpu - 禁用GPU硬件加速

定位策略

多种方式在页面上查找元素：

• id - 根据元素ID查找（<div id="myElement">）
• css - 根据CSS选择器查找（div.class-name, #id-name）
• xpath - 根据XPath表达式查找（//div[@class='example']）
• name - 根据名称属性查找（<input name="username">）
• tag - 根据HTML标签名查找（div, span, input）
• class - 根据类名查找（class-name）

超时配置

大多数工具接受可选的timeout参数（默认：10000ms）：

{
  "by": "id",
  "value": "submit-button",
  "timeout": 15000
}

要求

• Node.js 22+
• npm 或 pnpm
• 浏览器驱动程序（由Selenium自动管理）
• TypeScript 5.0+（开发依赖）

故障排除

常见问题

• 驱动未找到：Selenium自动下载驱动程序，但确保已安装目标浏览器
• 权限错误：在Linux上，可能需要安装浏览器包（chromium-browser, firefox等）
• 超时错误：对于加载缓慢的页面，增加超时值
• 无头模式问题：某些功能在无头模式下可能无法正常工作（文件上传、某些交互）

平台特定说明

• macOS：Safari需要在Safari偏好设置中启用自动化
• Linux：可能需要额外的依赖项以支持GUI浏览器
• Windows：应与标准浏览器安装一起开箱即用

许可证

MIT许可证 - 详情见LICENSE文件。

致谢

灵感来自@angiejones/mcp-selenium