Selenium Recorder MCP

Selenium测试录制器MCP服务器

使用Chrome DevTools Protocol（CDP）的MCP服务器，用于记录全面的浏览器交互。在您手动与网站交互时，记录DOM突变、控制台日志和JavaScript错误。

特点/特性

• 点击追踪捕获每个点击事件，并获取完整的元素详细信息（XPath、CSS选择器、属性、文本内容、坐标）
• 全面记录捕获DOM突变、控制台日志和JavaScript错误
• 手动交互在手动浏览和与浏览器交互时进行录制
• 敏感字段遮蔽自动遮蔽密码字段和其他敏感数据
• 智能过滤按事件类型、时间范围或分页查询录音记录 - 避免大量上下文数据导出
• 元数据优先在获取数据前查看事件细分 - 默认安全
• JSON 输出用于分析和测试生成的结构化数据
• 克劳德代码集成在Claude代码中使用MCP工具

最新动态

智能查询过滤（重大变更）

该 get_recording 工具现已返回 默认情况下仅显示元数据 以防止产生可能填满Claude上下文窗口的大型响应。

之前：

get_recording(session_id) → Returns all events (could be 70k+ tokens)

现在：

get_recording(session_id) → Returns metadata only (event breakdown, file path)
get_recording(session_id, limit=50) → Returns first 50 events
get_recording(session_id, event_types=["click"]) → Returns only click events

好处：

• ✅ 不再出现意外上下文溢出警告
• ✅ 在请求数据前查看可用内容
• ✅ 筛选至您所需的确切内容
• ✅ 对大型录音进行分页

迁移： 添加任何过滤参数以获取事件（例如。， limit， event_types， offset)

见 使用过滤器查询录音 详情见下文。

安装

cd selenium-recorder-mcp
uv venv
source .venv/bin/activate
uv pip install -e .

要求

• Python 3.10+（或“Python 3.10及以上版本”）
• Google Chrome（或基于Chromium的浏览器）
• macOS、Linux 或 Windows

快速入门（独立脚本）

最简单的使用方法——无需MCP设置：

cd selenium-recorder-mcp
source .venv/bin/activate
python record.py https://www.example.com

这将会：

1. 在URL中打开Chrome浏览器
2. 开始记录点击事件、DOM 变异、控制台日志和 JavaScript 错误
3. 允许您手动进行交互（登录、导航、点击等）
4. 完成后按 ENTER 键停止录制
5. 保存录音至 recordings/ 文件夹作为JSON格式

示例输出：

✅ Recording started!
📝 Session ID: 550e8400-e29b-41d4-a716-446655440000
🌐 Chrome opened at: https://www.example.com

👉 Interact with the browser now...
   Press ENTER when done to stop recording

[... you interact with the browser ...]

⏹️  Stopping recording...
✅ Recording saved to: recordings/550e8400_20250930_143022.json
📊 Total events: 247

📈 Summary:
   - Clicks: 12
   - DOM mutations: 189
   - Console logs: 52
   - JS errors: 6
   - Masked events: 3

设置（MCP服务器集成）

配置Claude代码MCP

方法1：使用 claude mcp add 命令（推荐）

在您的终端中运行：

claude mcp add selenium-recorder \
  --scope user \
  -- /bin/zsh -lc '
    cd /path/to/selenium-recorder-mcp &&
    exec ./.venv/bin/python -m src.server
  '

替换 /path/to/selenium-recorder-mcp 与您的实际安装目录一致。

如果Chrome不在默认位置，请添加 --env 标志：

claude mcp add selenium-recorder \
  --scope user \
  --env CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  -- /bin/zsh -lc '
    cd /path/to/selenium-recorder-mcp &&
    exec ./.venv/bin/python -m src.server
  '

默认的Chrome路径：

• macOS： /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
• Linux： /usr/bin/google-chrome
• Windows： C:\Program Files\Google\Chrome\Application\chrome.exe

对于bash用户，请替换 /bin/zsh -lc 和；与 /bin/bash -lc

注：

• --scope user 使其在您所有的项目中均可使用
• 这个（或“该”） -lc 标志确保了一个带有适当环境设置的登录 shell
• exec 用Python替换shell进程，以实现更干净的进程管理

______________________________________________________________________

方法2：手动JSON配置（替代方案）

添加到您的Claude代码MCP设置中（~/.claude/mcp_settings.json):

{
  "mcpServers": {
    "selenium-recorder": {
      "command": "/path/to/selenium-recorder-mcp/.venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/selenium-recorder-mcp",
      "env": {
        "CHROME_PATH": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
      }
    }
  }
}

重要提示： 两者都使用绝对路径 command 并且 cwd 字段。

使用方法

方法1：独立脚本（推荐作为入门方式）

python record.py https://www.sport5.co.il

1. Chrome 自动打开
2. 手动进行交互（登录、导航、点击）
3. 按回车键停止
4. 录音已保存至 recordings/ 文件夹

然后，将录制的JSON文件与Claude Code共享，以便进行分析或生成测试！

方法2：MCP服务器（高级 - 与Claude代码集成）

配置完MCP设置并重启Claude Code后：

工作流程：

1. 开始录音 - 打开Chrome并开始录制
2. 手动交互 - 登录、浏览、与网站互动
3. 停止录制 - 将事件保存到JSON文件
4. 分析/生成 - 使用Claude Code来分析或生成测试代码

MCP 工具：

start_recording

开始录制浏览器会话。

参数：

• url （可选）：启动时要导航到的URL
• sensitive_selectors （可选）：针对敏感字段的额外CSS选择器

返回值： 会话ID

示例：

start_recording with url "https://example.com"

stop_recording

停止录制并保存为JSON格式。

参数：

• session_id （必需）：来自start_recording的会话ID

返回值： 保存录音的文件路径

示例：

stop_recording with session_id "abc-123-def"

get_recording

检索录制元数据或筛选事件。

参数：

• session_id （必需）：用于检索的会话ID
• event_types （可选）：用于过滤的事件类型数组（例如。， ["click", "console_log"])
• limit （可选）：要返回的最大事件数
• offset （可选）：要跳过的事件数量（用于分页）
• from_timestamp （可选）：ISO 时间戳 - 仅返回此时间之后的事件
• to_timestamp （可选）：ISO 时间戳 - 仅返回此时间之前的事件

返回值：

• 没有过滤器仅元数据（事件类型细分、文件路径、总计数）——避免响应过大
• 使用任何过滤器符合标准的筛选事件

示例：

# Get metadata only (safe, no large dumps)
get_recording with session_id "abc-123"

# Get first 50 events
get_recording with session_id "abc-123" and limit 50

# Get only click events
get_recording with session_id "abc-123" and event_types ["click"]

# Get clicks and DOM changes
get_recording with session_id "abc-123" and event_types ["click", "dom_attribute_modified"]

analyze_recording

获取汇总统计数据。

参数：

• session_id （必填）：要分析的会话ID

返回： 事件摘要及统计数量

与Claude代码的示例会话

You: Start recording https://myapp.com/login

Claude: [calls start_recording]
Recording started. Session ID: 550e8400-e29b-41d4-a716-446655440000
Chrome browser opened at https://myapp.com/login.
Interact with the browser manually. Call stop_recording when done.

[You manually login and navigate through the app]

You: Stop recording with session_id 550e8400-e29b-41d4-a716-446655440000

Claude: [calls stop_recording]
Recording stopped and saved to: recordings/550e8400-e29b-41d4-a716-446655440000_20250115_143022.json
Total events recorded: 247

You: What's in the recording?

Claude: [calls get_recording with session_id only - no filters]
Session: 550e8400-e29b-41d4-a716-446655440000
File: recordings/550e8400-e29b-41d4-a716-446655440000_20250115_143022.json
Total events: 247

Event type breakdown:
  dom_attribute_modified: 89
  console_log: 52
  dom_set_child_nodes: 45
  click: 12
  dom_character_data_modified: 43
  js_error: 6

ℹ️  Use filters to retrieve events (limit, event_types, offset, timestamps)
Or read the file directly.

You: Show me just the click events

Claude: [calls get_recording with event_types=["click"]]
Session: 550e8400-e29b-41d4-a716-446655440000
Events: 12/247
Filters: {"event_types": ["click"]}

[Returns 12 click events with full details]

You: Generate a Selenium test from the click events

Claude: [uses the 12 click events to generate test code]

使用过滤器查询录音

这个（或“该”） get_recording 该工具现已支持强大的过滤功能，以避免生成大型上下文转储，并仅检索您所需的数据。

默认行为（仅限元数据）

没有任何过滤器， get_recording 仅返回元数据：

get_recording with session_id "abc-123"

返回值：

• 会话信息（URL、时间戳、文件路径）
• 总事件数
• 事件类型细分（显示每种事件类型的数量）
• 使用说明
• 没有活动 - 防止意外地在上下文中填充大量回复内容

这是 默认安全 并在你请求特定数据之前，帮助你理解录音中的内容。

使用过滤器检索事件

要获取实际事件，请使用任意过滤参数：

限制事件（分页）

# First 50 events
get_recording with session_id "abc-123" and limit 50

# Next 50 events (pagination)
get_recording with session_id "abc-123" and limit 50 and offset 50

按事件类型筛选

# Only clicks
get_recording with session_id "abc-123" and event_types ["click"]

# Clicks and DOM mutations
get_recording with session_id "abc-123" and event_types ["click", "dom_attribute_modified", "dom_set_child_nodes"]

# Exclude noisy console logs - get everything else
get_recording with session_id "abc-123" and event_types ["click", "js_error", "dom_attribute_modified"]

时间范围过滤

# Events after a specific time
get_recording with session_id "abc-123" and from_timestamp "2025-01-15T14:30:00"

# Events in a time window
get_recording with session_id "abc-123" and from_timestamp "2025-01-15T14:30:00" and to_timestamp "2025-01-15T14:35:00"

组合过滤器

# Click events only, first 100
get_recording with session_id "abc-123" and event_types ["click"] and limit 100

# Recent errors only
get_recording with session_id "abc-123" and event_types ["js_error"] and from_timestamp "2025-01-15T14:30:00"

过滤器可扩展性

过滤器是 事件类型无关（或：不依赖于事件类型） 并且能处理任何类型的事件：

• 当前事件类型： click， console_log， js_error， dom_attribute_modified， dom_set_child_nodes， dom_character_data_modified， document_updated
• 当添加新的事件类型时（例如。， window_resize， network_request)，它们是 可立即过滤 无需更改代码
• 只需在（相应位置）使用事件类型名称 event_types 数组

典型工作流程

1. 获取概览 - 不使用过滤器进行呼叫以查看事件细分
2. 筛选出你需要的内容 - 请求特定的事件类型或范围
3. 如有需要，请分页 - 使用 limit 和 offset 对于大型结果集
4. 生成/分析 - 使用过滤后的数据进行测试生成或分析

示例：

# Step 1: What's in the recording?
get_recording with session_id "abc-123"
→ Shows: 514 events (click: 45, console_log: 320, js_error: 12, ...)

# Step 2: I only care about user interactions
get_recording with session_id "abc-123" and event_types ["click"]
→ Returns: 45 click events

# Step 3: Generate test from clicks
[Claude uses 45 click events to generate Selenium test]

输出格式

录音以JSON格式保存：

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://example.com",
  "start_time": "2025-01-15T14:30:15.123456",
  "end_time": "2025-01-15T14:35:22.654321",
  "events": [
    {
      "type": "dom_attribute_modified",
      "timestamp": "2025-01-15T14:30:18.123456",
      "data": {
        "node_id": 42,
        "name": "value",
        "value": "***MASKED***",
        "_masked": true
      }
    },
    {
      "type": "console_log",
      "timestamp": "2025-01-15T14:30:20.123456",
      "data": {
        "level": "info",
        "args": ["User logged in successfully"]
      }
    },
    {
      "type": "js_error",
      "timestamp": "2025-01-15T14:30:25.123456",
      "data": {
        "message": "TypeError: Cannot read property 'id' of undefined",
        "stack": "..."
      }
    }
  ],
  "metadata": {
    "saved_at": "2025-01-15T14:35:22.987654",
    "event_count": 247
  }
}

敏感字段遮蔽

默认情况下，这些字段会被遮蔽：

• input[type="password"]
• input[name*="password"]
• input[name*="passwd"]
• input[id*="password"]
• input[name*="secret"]
• input[name*="token"]

添加自定义敏感选择器：

start_recording with sensitive_selectors ["input[name='credit-card']", "input[id='ssn']"]

事件类型

点击事件

• click用户点击交互，包含全面的元素详情：

- 识别标签名、ID、类、所有属性 - 内容文本内容（前200个字符），innerHTML（前500个字符） - 选择器XPath和CSS选择器用于精确定位元素 - 链接/媒体href（用于链接），src（用于图像） - 位置点击坐标(x, y)和页面位置 - 上下文视口大小和当前URL

示例点击事件：

{
  "type": "click",
  "timestamp": "2025-01-15T14:30:22.123456",
  "data": {
    "tagName": "A",
    "id": "login-button",
    "className": "btn btn-primary",
    "classList": ["btn", "btn-primary"],
    "attributes": {"href": "/login", "target": "_self"},
    "textContent": "Login",
    "innerHTML": "Login",
    "xpath": "//*[@id=\"login-button\"]",
    "cssSelector": "#login-button",
    "href": "https://example.com/login",
    "coordinates": {"x": 150, "y": 200, "pageX": 150, "pageY": 200},
    "viewport": {"width": 1920, "height": 1080},
    "url": "https://example.com"
  }
}

DOM 事件

• document_updated文档结构已更改
• dom_set_child_nodes子节点已添加/修改
• dom_attribute_modified元素属性已更改
• dom_character_data_modified文本内容已更改

运行时事件

• console_log控制台输出（日志、信息、警告、错误）
• js_error抛出JavaScript异常

故障排除

Chrome无法打开

• 检查 CHROME_PATH 是正确的
• 确保已安装Chrome浏览器
• 尝试使用Chrome可执行文件的绝对路径

未记录任何事件

• 检查 Chrome DevTools 控制台中的错误
• 确保页面允许远程调试
• 某些CSP（内容安全策略）政策可能会阻止CDP（内容分发协议）

MCP服务器无法从另一个文件夹连接

• 在（文件/程序等）中使用绝对路径 mcp_settings.json 用于/对于 command 田野
• 示例： "/Users/username/selenium-recorder-mcp/.venv/bin/python"
• 这个（或“它”） cwd 设置仅影响进程的运行位置，而不会影响命令的查找位置

敏感数据未被遮蔽

• 通过添加自定义选择器 sensitive_selectors
• 检查字段命名模式是否与默认值匹配
• 审查 event_processor.py 中的模式

用例

1. 测试生成记录手动工作流程，生成Selenium测试
2. 错误重现在错误发生时捕获精确的DOM状态
3. 性能分析追踪DOM突变和控制台日志
4. 调试在交互过程中查看所有浏览器事件

建筑学

┌─────────────────┐
│  Claude Code    │
│   (MCP Client)  │
└────────┬────────┘
         │
         │ MCP Protocol
         │
┌────────▼────────┐
│  server.py      │  MCP Tools
│  (MCP Server)   │  - start_recording
└────────┬────────┘  - stop_recording
         │           - get_recording
         │           - analyze_recording
         │
┌────────▼──────────────────────────┐
│  cdp_recorder.py                  │
│  - Launch Chrome w/ debug port    │
│  - Connect via CDP                │
│  - Inject click tracking JS       │
│  - Listen to DOM/Runtime events   │
└────────┬──────────────────────────┘
         │
┌────────▼──────────────────────────┐
│  event_processor.py               │
│  - Mask sensitive fields          │
│  - Enrich events                  │
│  - Analyze patterns               │
└────────┬──────────────────────────┘
         │
┌────────▼──────────────────────────┐
│  storage.py                       │
│  - Save as JSON                   │
│  - Load recordings                │
│  - List/delete                    │
└───────────────────────────────────┘

发展

直接运行服务器：

python -m src.server

许可证

麻省理工学院（MIT）