AI导哈

浏览器自动化服务器

Selenium MCP Server 是一个基于 Selenium Grid 的浏览器自动化服务器，提供35+工具支持AI代理逐步驱动浏览器操作，适用于自动化测试和网页交互场景。

  • by mlamoure
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 mlamoure/selenium-mcp-server

使用说明

Selenium MCP服务器

一种模型上下文协议（MCP）服务器，通过Selenium Grid提供浏览器自动化功能。AI代理可以使用MCP工具逐步驱动web浏览器，而不是直接编写Selenium脚本。

建筑

内置于 FastMCP 2.0 使用 可流式HTTP传输 用于自托管部署。在您的基础设施上部署一次，并从任何MCP客户端远程连接。

  • 可流式传输的HTTP -支持流媒体的原生HTTP传输
  • Selenium网格后端 -将浏览器实例与MCP服务器分离，以实现独立扩展
  • 集中式端点 -单个服务器为多个AI代理/客户端提供服务

特性

  • 35+MCP工具 实现浏览器的完全自动化
  • 会话管理 具有自动超时和清理功能
  • 元素注册表 用于跨工具调用的稳定元素引用
  • 域护栏 将导航限制到允许的域
  • 结构化错误 为人工智能恢复提供有益的建议
  • Docker支持 包含Selenium Grid

快速开始

从容器注册表部署（推荐）

直接部署，无需克隆存储库。创建一个 docker-compose.yml:

services:
  selenium-mcp:
    image: ghcr.io/mlamoure/selenium-mcp-server:latest
    ports:
      - "8000:8000"
    environment:
      - SELENIUM_MCP_SELENIUM_GRID_URL=http://selenium-hub:4444
    depends_on:
      selenium-hub:
        condition: service_healthy
    restart: unless-stopped

  selenium-hub:
    image: selenium/hub:4.25
    ports:
      - "4444:4444"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4444/status"]
      interval: 10s
      timeout: 5s
      retries: 5

  chrome-node:
    image: selenium/node-chrome:4.25
    shm_size: 2g
    environment:
      - SE_EVENT_BUS_HOST=selenium-hub
      - SE_EVENT_BUS_PUBLISH_PORT=4442
      - SE_EVENT_BUS_SUBSCRIBE_PORT=4443
      - SE_NODE_MAX_SESSIONS=4
    depends_on:
      selenium-hub:
        condition: service_healthy

docker-compose up -d

# MCP server: http://localhost:8000/mcp/
# Selenium Grid UI: http://localhost:4444

使用Docker Compose（源代码）

git clone https://github.com/mlamoure/selenium-mcp-server.git
cd selenium-mcp-server
docker-compose up -d

# MCP server: http://localhost:8000/mcp/
# Selenium Grid UI: http://localhost:4444

手动安装

# Requires Python 3.12+ and a running Selenium Grid
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Set Grid URL and run
export SELENIUM_MCP_SELENIUM_GRID_URL=http://localhost:4444
python -m selenium_mcp

工具类别

会话管理

  • create_session -创建新的浏览器会话（可选视频录制）
  • close_session -关闭浏览器会话
  • get_session_info -获取详细的会话信息，包括录制状态
  • list_sessions -列出所有活动会话
  • ping -健康检查

导航

  • navigate -转到URL
  • reload_page -刷新当前页面
  • navigate_back / navigate_forward -浏览器历史记录
  • get_page_info -获取当前URL、标题和就绪状态

观察

  • get_dom -获取页面HTML（可选脚本/样式剥离）
  • get_visible_text -获取所有可见的文本内容
  • query_elements -查找元素并获得稳定的ID
  • get_screenshot -捕获页面截图
  • get_console_logs -获取浏览器控制台日志

行动

  • click_element / click_selector -点击元素
  • type_text -在输入字段中键入
  • clear_element -明确输入内容
  • set_checkbox_state -选中/取消选中复选框
  • select_dropdown_option -从下拉菜单中选择
  • scroll_to_element / scroll_by -滚动页面
  • hover_element -鼠标悬停
  • drag_drop -拖放
  • send_keys -发送键盘按键
  • upload_file -上传文件

等待

  • wait_for_selector -等待元素（存在/可见/可点击/隐藏）
  • wait_for_url -等待URL与模式匹配
  • wait_for_ready_state -等待文档就绪状态
  • wait_for_text -等待文本出现

JavaScript

  • execute_script -运行同步JavaScript
  • execute_async_script -运行异步JavaScript

配置

通过环境变量进行配置（前缀： SELENIUM_MCP_):

变量 描述 默认值
SELENIUM_GRID_URL Selenium网格端点 http://localhost:4444
DEFAULT_BROWSER 默认浏览器类型 chrome
MAX_CONCURRENT_SESSIONS 最大并发会话数 10
SESSION_MAX_LIFETIME_SECONDS 会话自动关闭超时 900
SESSION_MAX_IDLE_SECONDS 空闲会话超时 300
RECORDING_DEFAULT 默认视频录制状态 true
RECORDING_FORCE 强制录制设置（忽略客户端） false
ALLOWED_DOMAINS 逗号分隔的允许域 （全部允许）
DOM_MAX_CHARS get_dom的最大字符数 20000
DEFAULT_WAIT_TIMEOUT_MS 默认等待超时 10000
HOST 服务器绑定地址 0.0.0.0
PORT 服务器端口 8000

视频录制

当使用带有视频录制Sidecar的Selenium Grid时，可以录制会话以进行调试和审查。通过以下方式控制录制 se:recordVideo 硒能力。

配置

  • RECORDING_DEFAULT -何时 true （默认），除非明确禁用，否则会话会录制视频
  • RECORDING_FORCE -何时 true，忽略客户端首选项并使用 RECORDING_DEFAULT 对于所有会话

用法

# Create session with recording (uses server default if not specified)
result = await client.call_tool("create_session", {
    "browser": "chrome",
    "record_video": True  # Optional: explicitly enable/disable
})

# Response includes recording info
# {
#   "session_id": "sess_abc123",
#   "record_video": true,
#   "selenium_session_id": "abc123-def456-..."  # Grid session ID for video retrieval
# }

视频检索

这 selenium_session_id 在响应中是Selenium Grid的内部会话ID。使用此ID在Grid的视频存储中查找录制的视频。确切的检索方法取决于您的网格配置。

示例用法

# Typical AI agent workflow:

# 1. Create a session (recording enabled by default)
result = await client.call_tool("create_session", {"browser": "chrome"})
session_id = result["session_id"]

# 2. Navigate to a page
await client.call_tool("navigate", {
    "session_id": session_id,
    "url": "https://example.com"
})

# 3. Find elements
elements = await client.call_tool("query_elements", {
    "session_id": session_id,
    "strategy": "css",
    "selector": "button.submit"
})

# 4. Click an element
await client.call_tool("click_element", {
    "session_id": session_id,
    "element_id": elements["elements"][0]["element_id"]
})

# 5. Wait for navigation
await client.call_tool("wait_for_url", {
    "session_id": session_id,
    "pattern": "success"
})

# 6. Close session when done
await client.call_tool("close_session", {"session_id": session_id})

错误处理

所有工具返回结构化错误，包括：

  • error_code -机器可读代码（例如。， ELEMENT_NOT_FOUND)
  • message -人类可读的描述
  • suggestion -AI的恢复提示

示例错误：

{
  "success": false,
  "error": {
    "code": "ELEMENT_NOT_FOUND",
    "message": "Element not found: css=#missing",
    "suggestion": "Verify the selector is correct. Use wait_for_selector before querying if the element loads dynamically."
  }
}

发展

# Install dev dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

# Lint
ruff check src/

许可证

麻省理工学院

相关 MCP