selenium-ai-agent

AI-powered Selenium MCP server for browser automation — 75 tools with accessibility tree discovery, selector teaching, BiDi cross-browser support, Selenium Grid parallel execution, test generation & self-healing pipeline, and session tracing.

One-Click Install

Install

npm install -g selenium-ai-agent

Or run directly without installing:

npx selenium-ai-agent

Requirements

• Node.js 18+
• Chrome browser (or Firefox/Edge)
• ChromeDriver is automatically managed by selenium-webdriver

Quick Start

Add to your MCP client config:

{
  "mcpServers": {
    "selenium-mcp": {
      "command": "npx",
      "args": ["selenium-ai-agent"]
    }
  }
}

Then ask your AI assistant: "Navigate to https://example.com and take a screenshot"

Client Setup

Claude Code

claude mcp add selenium-mcp -- npx selenium-ai-agent

Or add to your project .mcp.json:

{
  "mcpServers": {
    "selenium-mcp": {
      "command": "npx",
      "args": ["selenium-ai-agent"]
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "selenium-mcp": {
      "command": "npx",
      "args": ["selenium-ai-agent"]
    }
  }
}

Config paths per OS:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "selenium-mcp": {
      "command": "npx",
      "args": ["selenium-ai-agent"]
    }
  }
}

GitHub Copilot (VS Code 1.99+)

Add to .vscode/mcp.json:

{
  "servers": {
    "selenium-mcp": {
      "command": "npx",
      "args": ["selenium-ai-agent"],
      "type": "stdio"
    }
  }
}

Note: Copilot uses "servers" instead of "mcpServers".

Cline

Open the MCP Servers panel in Cline, click Configure, then Advanced MCP Settings, and add:

{
  "mcpServers": {
    "selenium-mcp": {
      "command": "npx",
      "args": ["selenium-ai-agent"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json (global) or .windsurf/mcp_config.json (project):

{
  "mcpServers": {
    "selenium-mcp": {
      "command": "npx",
      "args": ["selenium-ai-agent"]
    }
  }
}

Tool Auto-Approval (Reducing "Yes" Prompts)

All tools include MCP annotations (readOnlyHint, destructiveHint, etc.) that help clients auto-approve safe tools. Read-only tools like capture_page, recording_status, and grid_status are marked as non-destructive and can be auto-approved by clients that support annotations.

Claude Desktop

After the first approval, click "Always allow" for each tool to stop future prompts. Tools marked readOnlyHint: true may be auto-approved by the client.

Claude Code

Use --allow-mcp selenium-mcp to pre-approve all tools from this server:

claude --allow-mcp selenium-mcp

Or configure in .claude/settings.json:

{
  "permissions": {
    "allow": ["mcp__selenium-mcp__*"]
  }
}

Cursor / Cline / Windsurf

These clients typically allow you to configure auto-approval per tool or per server in their settings. Check your client's MCP settings for "auto-approve" or "always allow" options.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | SELENIUM_GRID_URL | — | Grid hub URL (enables parallel features) | | SELENIUM_BROWSER | chrome | Browser to use (chrome, firefox, edge) | | SELENIUM_HEADLESS | false | Run browser in headless mode | | SELENIUM_STEALTH | false | Enable stealth mode (hide automation indicators) | | SELENIUM_MCP_OUTPUT_MODE | stdout | Output mode: stdout (return data to LLM) or file (save to disk) | | SELENIUM_MCP_OUTPUT_DIR | auto | Output directory for generated files (auto-detected from project root) | | SELENIUM_MCP_SAVE_TRACE | false | Save session trace JSON to <output>/traces/ | | SELENIUM_MCP_UNRESTRICTED_FILES | false | Bypass workspace path validation (allow writing outside output dir) | | SE_AVOID_STATS | — | Set to true to disable Selenium usage statistics |

Pass env vars in your MCP config:

{
  "mcpServers": {
    "selenium-mcp": {
      "command": "npx",
      "args": ["selenium-ai-agent"],
      "env": {
        "SELENIUM_HEADLESS": "true",
        "SELENIUM_STEALTH": "true",
        "SE_AVOID_STATS": "true"
      }
    }
  }
}

CLI Flags

npx selenium-ai-agent [flags]

| Flag | Description | |------|-------------| | --stealth | Enable stealth mode | | --headless | Run browser headless | | --save-trace | Save session trace JSON | | --output-mode=stdout\|file | Set output mode | | --output-dir=<path> | Set output directory | | --grid-url=<url> | Set Selenium Grid hub URL | | --allow-unrestricted-file-access | Bypass workspace file path validation |

Tools (75)

Navigation (5)

| Tool | Description | |------|-------------| | navigate_to | Navigate the browser to a URL. Starts browser automatically if not running. | | go_back | Navigate back in browser history. | | go_forward | Navigate forward in browser history. | | refresh_page | Refresh the current page. | | scroll_page | Scroll the page in a direction (up/down/left/right) by pixel amount, or scroll a specific element into view by CSS selector. |

Page Analysis (2)

| Tool | Description | |------|-------------| | capture_page | Capture the current page state as an accessibility tree — returns elements with ARIA roles, semantic hierarchy, and refs (e1, e2, ...). Discovers up to 300 elements with visibility-aware selectors, ancestor scoping, and Shadow DOM traversal. Read-only. | | take_screenshot | Take a screenshot (viewport, full-page, or element). Uses BiDi when available for full-page/element screenshots, falls back to classic API. Params: origin (viewport/document), ref (element), format (png/jpeg), quality. |

Elements (5)

| Tool | Description | |------|-------------| | click_element | Click an element using its ref from the page snapshot. | | hover_element | Hover over an element using its ref. | | select_option | Select a dropdown option by value, text, or index. | | drag_drop | Drag from one element to another using refs. | | teach_selector | Teach the system a preferred CSS selector for an element. Saved as Phase 0 (highest priority) in future element discovery on that domain. Auto-scopes to site-wide for header/nav/footer elements, or path-specific for content. |

Input (3)

| Tool | Description | |------|-------------| | input_text | Type text into an input field or textarea. | | key_press | Press a keyboard key, optionally with modifiers (ctrl, alt, shift, meta). | | file_upload | Upload a file through a file input element. |

Mouse (3)

| Tool | Description | |------|-------------| | mouse_move | Move mouse to specific coordinates. | | mouse_click | Click at coordinates with specified button (left, right, middle). | | mouse_drag | Drag from one position to another. |

Tabs (4)

| Tool | Description | |------|-------------| | tab_list | List all open browser tabs with titles and URLs. Read-only. | | tab_select | Switch to a specific browser tab. | | tab_new | Open a new browser tab, optionally navigating to a URL. | | tab_close | Close a specific browser tab. |

Verification (4)

| Tool | Description | |------|-------------| | verify_element_visible | Verify that an element is visible on the page (with timeout). Read-only. | | verify_text_visible | Verify that specific text is visible on the page (with timeout). Read-only. | | verify_value | Verify that an input element has the expected value. Read-only. | | verify_list_visible | Verify that multiple text items are all visible on the page. Read-only. |

Browser (7)

| Tool | Description | |------|-------------| | wait_for | Wait for a condition: element visible, clickable, present, URL contains, or title contains. | | execute_javascript | Execute JavaScript code in the browser context with optional return value. | | resize_window | Resize the browser window to specified dimensions. | | dialog_handle | Handle browser dialogs (alert, confirm, prompt). | | console_logs | Get or clear browser console logs. Uses BiDi event collector when available for cross-browser support, falls back to classic log API. | | network_monitor | Monitor network requests: get requests, clear, or toggle offline mode. | | pdf_generate | Generate a PDF from the current page. Uses BiDi printPage for cross-browser support (Chrome, Firefox, Edge), falls back to CDP. Params: format, landscape, scale, pageRanges. Optional filePath — omit to return as base64 resource. |

Session (3)

| Tool | Description | |------|-------------| | close_browser | Close the browser and end the session. | | reset_session | Reset the browser session (close and restart). | | set_stealth_mode | Enable/disable stealth mode — hides navigator.webdriver, patches plugins, sets realistic languages. |

Recording (4)

| Tool | Description | |------|-------------| | start_recording | Start recording browser actions for test script generation. | | stop_recording | Stop recording and return full action log with element locators and framework hint. | | recording_status | Check if recording is active and show recent actions. Read-only. | | clear_recording | Clear all recorded browser actions. |

Test Planner (3)

| Tool | Description | |------|-------------| | planner_setup_page | Initialize test planning — navigate to app and start exploring. | | planner_explore_page | Explore a page in detail, discovering elements, forms, and links. | | planner_save_plan | Save completed test plan to a markdown file. |

Test Generator (6)

| Tool | Description | |------|-------------| | generator_setup_page | Initialize test generation session — navigate to app, start recording, set framework. | | generator_read_log | Retrieve the action log from the recording session. Read-only. | | generator_write_test | Save generated test code and update .test-manifest.json. Supports verify (validates selectors against live page) and specFile (links to spec). | | generator_write_seed | Write a seed/bootstrap test (auth, fixtures, env setup) and register in manifest under seedTests[]. | | generator_save_spec | Save a structured markdown spec to <output>/specs/. | | generator_read_spec | Read a spec file. Read-only. |

Test Healer (5)

| Tool | Description | |------|-------------| | healer_run_tests | Execute tests and return output. Supports manifest mode (reads .test-manifest.json) or explicit mode (provide command + args). Runs seed tests first when present. | | healer_debug_test | Run a single test in verbose mode with detailed output (15KB stdout, 8KB stderr). | | healer_fix_test | Apply a fix to a test file with .bak backup. Supports verify (validates selectors in fixed code). | | healer_inspect_page | Inspect current page against expected locators — reports found, missing, and changed elements with suggested updated locators. Use after test failure to understand UI drift. | | browser_generate_locator | Generate robust locator strategy for an element by description. Read-only. |

Regression Analyzer (6)

| Tool | Description | |------|-------------| | analyzer_setup | Initialize regression analysis session with product URL and business context. | | analyzer_import_context | Import additional context from files, inline text, or URLs. | | analyzer_scan_product | Explore product using process walking and page scanning. | | analyzer_build_risk_profile | Build risk profile from discovered features and context. Read-only. | | analyzer_save_profile | Save risk profile to YAML or JSON file. | | analyzer_generate_documentation | Generate product discovery documentation with screenshots. |

Batch (1)

| Tool | Description | |------|-------------| | batch_execute | Execute up to 20 tool steps in a single round trip. Intermediate steps skip snapshots for speed. |

Grid Management (4)

| Tool | Description | |------|-------------| | grid_status | Check Grid status — nodes, browsers, capacity. Read-only. | | grid_start | Start Selenium Grid via Docker Compose with configurable Chrome/Firefox node counts. | | grid_stop | Stop Selenium Grid. | | grid_scale | Scale Grid to desired number of browser nodes. |

Grid Sessions (5)

| Tool | Description | |------|-------------| | session_create | Create a new browser session on the Grid. | | session_select | Select a grid session as active browser for all subsequent tool calls. | | session_list | List all active Grid sessions, optionally filtered by tags. Read-only. | | session_destroy | Destroy a specific Grid session. | | session_destroy_all | Destroy all Grid sessions, optionally filtered by tags. |

Grid Parallel Execution (3)

| Tool | Description | |------|-------------| | parallel_explore | Explore multiple URLs in parallel — each target gets its own Grid session. | | parallel_execute | Execute multiple task sequences in parallel across Grid sessions. | | planner_generate_plan | Generate structured test plan from parallel exploration results. |

Grid Exploration Analysis (2)

| Tool | Description | |------|-------------| | exploration_merge | Merge multiple exploration results, deduplicate pages, build site map. Read-only. | | exploration_diff | Compare two exploration results — find added, removed, and changed pages. Read-only. |

Expectation System

Every tool accepts an optional expectation parameter to control what data is included in the response:

{
  "expectation": {
    "includeSnapshot": true,
    "includeConsole": true,
    "includeNetwork": true,
    "snapshotOptions": { "selector": "#main", "maxLength": 5000 },
    "consoleOptions": { "levels": ["error", "warn"], "maxMessages": 10 },
    "diffOptions": { "enabled": true, "format": "unified" }
  }
}

| Option | Description | |--------|-------------| | includeSnapshot | Include page snapshot (element list) in the response | | includeConsole | Include browser console logs | | includeNetwork | Include network request summary (requires BiDi) | | snapshotOptions.selector | CSS selector to scope element discovery | | snapshotOptions.maxLength | Truncate snapshot text at this length | | consoleOptions.levels | Filter by log level: error, warn, info, log | | diffOptions.enabled | Return only changes since last snapshot | | diffOptions.format | Diff format: minimal or unified |

Each tool category has sensible defaults (e.g., navigation tools include snapshot, verification tools don't).

BiDi Cross-Browser Features

The server uses WebDriver BiDi protocol (always enabled) for cross-browser features that go beyond what the classic WebDriver API offers:

• Full-page screenshots — take_screenshot with origin: "document" captures the entire scrollable page, not just the viewport
• Element screenshots — take_screenshot with ref: "e5" captures a specific element
• Cross-browser PDF — pdf_generate works on Chrome, Firefox, and Edge (was Chrome-only with CDP)
• Console events — console_logs uses BiDi LogInspector for real-time console events across all browsers
• Network monitoring — BiDi network events provide request/response tracking
• Stealth mode — Injects preload scripts via BiDi script.addPreloadScript to mask automation indicators

BiDi features degrade gracefully — if a browser doesn't support a specific BiDi feature, the tool falls back to the classic API.

Selector Teaching & Hints

The teach_selector tool lets you override auto-computed selectors with your own preferred CSS selectors. Taught selectors are persisted to <output>/selector-hints.json and loaded as Phase 0 (highest priority) during element discovery on matching pages.

How It Works

1. Call teach_selector with a description and CSS selector while on the page
2. The selector is validated in-browser (must match exactly 1 visible element)
3. Scope is auto-determined: header/nav/footer elements default to site-wide (*), content elements default to the current path pattern
4. On subsequent page snapshots, matching hints are loaded and used before any auto-computation

Example

teach_selector({
  description: "the NL language link",
  css: "a[href='/nl/']",
  scope: "*"  // optional — auto-determined if omitted
})

Hints file structure (selector-hints.json):

{
  "example.com": {
    "*": [
      { "css": "a[href='/nl/']", "tag": "a", "text": "NL" }
    ],
    "/blog/*": [
      { "css": "#post-title", "tag": "h1", "text": "My Post" }
    ]
  }
}

Element Discovery

The server uses a 16-phase selector computation engine that produces human-readable, semantically meaningful CSS and XPath selectors for every discovered element.

Selector Priority (Phases 0–16)

| Phase | Strategy | Example | |-------|----------|---------| | 0 | Taught hints | User-taught a[href="/nl/"] | | 1 | By ID | #login-form | | 2 | By test ID | [data-testid="submit-btn"] | | 2b | By descendant test ID | form:has([data-testid="email"]) | | 3 | By role + name | button[aria-label="Close"] | | 4 | By label | //label[normalize-space()='Email']//input | | 5 | By placeholder | input[placeholder="Search..."] | | 6 | By text | //a[normalize-space()='Sign In'] | | 7 | By attribute | a[hreflang="nl"], img[alt="Logo"] | | 9 | By ARIA role | [role="dialog"] | | 10 | By state | dialog[open], [aria-expanded] | | 11 | By table cell | #data-table > tbody > tr:nth-child(2) > td:nth-child(3) | | 12 | By compound attrs | input[type="email"][name="user"] | | 13 | By semantic class | button.primary-action | | 14 | By position | #sidebar > ul > li:nth-of-type(3) | | 15 | By text (loose) | //span[contains(normalize-space(),'Welcome')] | | 16 | By positional index | (//button[normalize-space()='Save'])[2] |

Key Capabilities

• Visibility-aware — only visible elements are counted for uniqueness, preventing hidden duplicates from causing fallbacks to fragile selectors
• Ancestor scoping — when a selector isn't unique globally, it's scoped to the nearest ancestor with an ID, test attribute, or landmark (nav[aria-label="Main"] a[href="/"])
• Shadow DOM — traverses open shadow roots, scopes CSS within shadow boundaries, uses >>> notation for cross-boundary selectors
• Two-pass discovery — semantic elements (links, buttons, headings) get refs first; generic elements with test attributes fill remaining budget
• Non-semantic class filtering — auto-skips CSS-in-JS hashes, Tailwind utilities, and framework-generated classes

Test Generation & Healing Pipeline

The generator and healer tools form a complete test automation pipeline:

1. Plan

planner_setup_page → planner_explore_page → planner_save_plan

2. Record & Generate

generator_setup_page → [interact with app] → stop_recording → generator_write_test

• Recording captures actions with element locators (id, name, text, aria-label)
• generator_write_test validates selectors against the live page before saving
• A .test-manifest.json is created alongside tests with framework, run command, and test list

3. Heal

healer_run_tests → healer_inspect_page → healer_fix_test → healer_run_tests

• healer_run_tests reads .test-manifest.json to auto-discover how to run tests
• healer_inspect_page compares expected locators against the live page to find UI drift
• healer_fix_test validates selectors in the fixed code before writing
• Seed tests (auth, fixtures) are run automatically before the main test when registered in the manifest

Spec Files

Save structured requirements as markdown specs before generating tests:

generator_save_spec → generator_write_test (with specFile param)

Session Tracing

Enable tracing to record every tool call and result as structured JSON:

npx selenium-ai-agent --save-trace

Or via env var:

{
  "env": { "SELENIUM_MCP_SAVE_TRACE": "true" }
}

Traces are saved to <output>/traces/session-<timestamp>.json on session close. Each trace entry records:

• Tool name and parameters
• Result content and error status
• Timestamps for performance analysis

Workspace Isolation

By default, all file-writing tools (screenshots, PDFs, test files, plans, analyzer output) validate that paths resolve within the output directory. This prevents accidental writes to system paths.

To override (e.g., for CI/CD or trusted environments):

npx selenium-ai-agent --allow-unrestricted-file-access

The healer_fix_test tool is exempt — it modifies existing project test files by design.

Selenium Grid

For parallel browser automation across multiple browsers, set SELENIUM_GRID_URL:

{
  "mcpServers": {
    "selenium-mcp": {
      "command": "npx",
      "args": ["selenium-ai-agent"],
      "env": {
        "SELENIUM_GRID_URL": "http://localhost:4444"
      }
    }
  }
}

Quick Start with Docker Compose

The project includes a Docker Compose file for local Grid setup:

# Start Grid with 4 Chrome + 1 Firefox nodes
grid_start

# Or use docker-compose directly
docker compose up -d

Parallel Workflows

Parallel exploration — explore multiple sections of a site simultaneously:

session_create (x3) → parallel_explore → exploration_merge

Parallel execution — run test steps across browsers:

session_create (chrome + firefox) → parallel_execute

Cross-browser testing — same actions on different browsers:

session_create (chrome) → session_create (firefox) → parallel_execute

See the project README for Docker Compose setup and Grid architecture details.

Output Mode

Control how binary data (screenshots, PDFs) is returned:

| Mode | Behavior | |------|----------| | stdout (default) | Return base64-encoded data to the LLM for inline display | | file | Save to disk in <output>/screenshots/ or <output>/pdfs/ |

npx selenium-ai-agent --output-mode=file

Architecture

selenium-mcp-server/src/
├── server.ts              # MCP server, tool routing, expectation system, tracing
├── context.ts             # Browser session state, EventCollector, SessionTracer
├── types.ts               # Core types (ToolResult, BrowserConfig, Expectation, Grid types)
├── types/
│   └── manifest.ts        # Shared test manifest types (generator ↔ healer)
├── bidi/
│   ├── event-collector.ts # BiDi event subscriptions (console, network, navigation)
│   └── index.ts
├── trace/
│   ├── session-tracer.ts  # Tool call + result recording
│   └── index.ts
├── utils/
│   ├── bidi-helpers.ts    # BiDi WebSocket URL rewriting + context factory
│   ├── chrome-options.ts  # Chrome options builder + stealth scripts
│   ├── element-discovery/   # Accessibility tree discovery (e1-e300)
│   │   ├── index.ts         # Barrel exports
│   │   ├── discover.ts      # discoverElements() with selector hints
│   │   ├── selector-scripts.ts # Browser-side computeSelector() (15 phases)
│   │   ├── tree-scripts.ts  # Browser-side accessibility tree walker
│   │   ├── format-tree.ts   # formatAccessibilityTree() (full/smart/minimal)
│   │   └── element-scripts.ts # extractElementInfo(), findElementByInfo()
│   ├── selector-hints.ts    # Persistent domain-scoped selector hint storage
│   ├── paths.ts           # Output directory resolution
│   ├── sandbox.ts         # Workspace path validation
│   ├── selector-validation.ts # Extract + validate selectors from test code
│   ├── schema.ts          # Zod → JSON Schema converter
│   └── docker.ts          # Docker Compose helpers
├── grid/
│   ├── grid-client.ts     # Grid REST API client
│   ├── grid-session.ts    # Remote browser session
│   ├── session-pool.ts    # Session lifecycle management
│   ├── session-context.ts # Context adapter for grid sessions
│   └── exploration-coordinator.ts
└── tools/                 # 75 tools grouped by domain
    ├── base.ts            # BaseTool abstract class + MCP annotations
    ├── index.ts           # Tool registry
    ├── navigation/        # navigate_to, go_back, go_forward, refresh_page, scroll_page
    ├── page/              # capture_page, take_screenshot
    ├── elements/          # click, hover, select, drag_drop, teach_selector
    ├── input/             # input_text, key_press, file_upload
    ├── mouse/             # mouse_move, mouse_click, mouse_drag
    ├── tabs/              # tab_list, tab_select, tab_new, tab_close
    ├── verification/      # verify_element_visible, verify_text, verify_value, verify_list
    ├── browser/           # wait, javascript, resize, dialog, console, network, pdf
    ├── session/           # close_browser, reset_session, set_stealth_mode
    ├── recording/         # start, stop, status, clear
    ├── agents/            # planner, generator, healer, spec tools
    ├── analyzer/          # setup, import, scan, risk, save, documentation
    ├── batch/             # batch_execute
    └── grid/              # 14 grid management + parallel execution tools

License

MIT