# selenium-ai-agent [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/learn-automated-testing/selenium_agent  
**GitHub Stars:** 3  
**npm Downloads (last month):** 213  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/selenium-ai-agent

## Description
AI-powered Selenium MCP server for browser automation — 74 tools with accessibility tree discovery, test generation, self-healing, and Selenium Grid parallel execution for AI agents

## Tools
Capabilities this server exposes over MCP:

- **navigate_to** — Navigate the browser to a URL. This is the primary and preferred navigation tool — starts a local browser automatically, no grid session or setup required. Use grid/session tools only when you need parallel browser sessions.
- **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 by a pixel amount, or scroll a specific element into view using a CSS selector.
- **capture_page** — Capture the current page state including all interactive elements. Returns a structured snapshot with element references (e1, e2, etc.) that can be used for interactions.
- **take_screenshot** — Take a screenshot of the current page, viewport, full page, or specific element. Uses BiDi for full-page and element screenshots when available, falls back to classic API.
- **click_element** — Click on an element using its reference from the page snapshot
- **hover_element** — Hover over an element using its reference from the page snapshot
- **select_option** — Select an option from a dropdown/select element by value, text, or index
- **drag_drop** — Drag and drop from source element to target element
- **teach_selector** — Teach the system a preferred CSS selector for an element. The selector is saved and used as Phase 0 (highest priority) in future element discovery on this domain.
- **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_move** — Move mouse to specific coordinates
- **mouse_click** — Click on an element using mouse with specified button
- **mouse_drag** — Drag from one element to another
- **tab_list** — List all open browser tabs
- **tab_select** — Switch to a specific browser tab by index
- **tab_new** — Open a new browser tab
- **tab_close** — Close a specific browser tab
- **verify_element_visible** — Verify that an element is visible on the page
- **verify_text_visible** — Verify that specific text is visible on the page
- **verify_value** — Verify that an element has the expected value or text content
- **verify_list_visible** — Verify that multiple text items are visible on the page
- **wait_for** — Wait for a condition to be met (element visible, URL contains, etc.)
- **execute_javascript** — Execute JavaScript code in the browser context. Use "return" to get a value back.
- **resize_window** — Resize the browser window to specified dimensions or a device preset (mobile, tablet, desktop, desktop-hd)
- **dialog_handle** — Handle browser dialogs (alert, confirm, prompt)
- **console_logs** — Get browser console logs or clear console. Uses BiDi event collector when available for cross-browser support, falls back to classic log API.
- **network_monitor** — Monitor network requests or control network state
- **pdf_generate** — Generate a PDF from the current page. Uses BiDi printPage for cross-browser support (Chrome, Firefox, Edge), falls back to CDP.
- **close_browser** — Close the browser and end the session
- **reset_session** — Reset the browser session (close and restart browser)
- **set_stealth_mode** — Enable or disable stealth mode for undetected browsing. Hides automation indicators like navigator.webdriver to avoid bot detection. If the browser is already running it will be restarted with the new setting.
- **start_recording** — Start recording browser actions to generate test scripts later
- **stop_recording** — Stop recording browser actions. Returns full action log with element locators.
- **recording_status** — Check if recording is active and show recorded actions
- **clear_recording** — Clear all recorded browser actions
- **planner_setup_page** — Initialize the testing environment and navigate to the application for test planning
- **planner_explore_page** — Explore a specific page in detail, discovering elements and forms
- **planner_save_plan** — Save the completed test plan to a markdown file
- **generator_setup_page** — Initialize the test generation session and navigate to the application.

When a framework is provided (e.g., from a skill), use it and apply its standard folder conventions. When no framework is specified, ask the user:

1. Which test framework? (selenium-python-pytest, playwright-js, webdriverio-ts, robot-framework, selenium-js-jest, selenium-js-mocha, selenium-java-maven, etc.)
2. Use the default structure for that framework? Defaults: pytest: tests/test_*.py, playwright: tests/*.spec.ts, webdriverio: test/specs/*.spec.ts, robot-framework: tests/*.robot, jest/mocha: test/*.test.js, java-maven: src/test/java/*Test.java
3. If not default, which pattern? (Page Object Model, BDD/Gherkin, Data-driven, Custom)

Pass the chosen framework to all subsequent generator and healer tool calls.
- **generator_read_log** — Retrieve the log of all actions performed during test generation session
- **generator_write_test** — Save generated test code to a file and update the .test-manifest.json.

The manifest records everything the healer needs to run tests later:
- framework, run command, config file, project root, base URL
- list of all generated test files

This means the healer can read the manifest and immediately know how to execute tests
without the LLM having to re-analyze the project each time.

The LLM can provide a custom runCommand, or let the tool suggest one based on the framework.
- **generator_write_seed** — Write a seed/bootstrap test (authentication, fixtures, environment setup).

Seed tests are registered in the manifest under seedTests[] and are run before
the main test suite by the healer. Use this for:
- Login/auth flows that save cookies or tokens
- Database seeding scripts
- Environment validation checks
- **generator_save_spec** — Save a structured markdown spec to the specs directory.

Specs capture test requirements in a human-readable format before generating test code.
Saved to <outputDir>/specs/<title-slug>.md
- **generator_read_spec** — Read a spec file from the specs directory
- **healer_run_tests** — Execute a test command and return stdout/stderr for failure analysis.

Two modes:
1. **Explicit**: Provide command + args + cwd directly (LLM has full control)
2. **Manifest**: Provide just testPath — the tool reads .test-manifest.json (created by generator_write_test) to get the run command, project root, and framework automatically.

Manifest mode example:
  { testPath: "/path/to/project/test/specs/tc07.spec.ts" }
  → Finds .test-manifest.json, reads runCommand, appends --spec testPath, runs it.

Explicit mode examples:
  { command: "npx", args: ["wdio", "run", "wdio.conf.ts", "--spec", "test/specs/tc07.spec.ts"], cwd: "/path/to/project" }
  { command: "pytest", args: ["tests/test_login.py", "-v", "--tb=short"], cwd: "/path/to/project" }
- **healer_debug_test** — Run a single test in debug/verbose mode and return detailed output.

Same as healer_run_tests but returns more output (15KB stdout, 8KB stderr) for deeper analysis.

Supports both explicit mode (command + args) and manifest mode (testPath only).
See healer_run_tests for details on both modes.
- **healer_fix_test** — Apply a fix to a test file. Creates a .bak backup before overwriting. The LLM provides the corrected code.
- **browser_generate_locator** — Generate a robust locator strategy for a specific element
- **healer_inspect_page** — Inspect the current page and compare expected locators against actual elements.

Use after a test failure to understand UI drift before applying a fix. Reports:
- Found elements (locator still works)
- Missing elements (locator broken, may need update)
- Suggested updated locators based on element discovery
- **analyzer_setup** — Initialize regression analysis session with product URL and business context
- **analyzer_import_context** — Import additional context from local files, inline text, or URLs to enrich the analysis
- **analyzer_scan_product** — Explore the product using both process walking (from imported context) and page scanning
- **analyzer_build_risk_profile** — Build comprehensive risk profile from discovered features and context
- **analyzer_save_profile** — Save the completed risk profile to a file
- **analyzer_generate_documentation** — Generate a comprehensive product discovery document with screenshots - serves as input for the Planner agent
- **batch_execute** — Execute multiple tool steps in a single round trip. Intermediate steps skip snapshots by default; the last step includes a snapshot. Max 20 steps. Cannot call batch_execute recursively.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "selenium-ai-agent": {
    "command": "npx",
    "args": ["-y","selenium-ai-agent"]
  }
}
```

## Documentation

## What selenium-ai-agent does

selenium-ai-agent exposes Selenium browser automation through MCP tools for AI agents. Its browser controls support actions such as navigating to a URL, entering text, clicking elements, verifying visible text, and capturing screenshots. Accessibility-tree discovery helps agents inspect page structure and identify interactive content during exploration.

The server also supports an agent workflow for planning and test creation. An agent can explore an application, save a test plan as Markdown, record browser interactions, and generate test files. Supported generation targets shown in the project examples include WebdriverIO with TypeScript, Playwright with JavaScript, and Selenium with Python and pytest. Robot Framework is also listed as a supported test-generation target.

## How it works

The basic setup starts the MCP process with `npx selenium-ai-agent`. An MCP client sends browser commands to the server, which opens and controls Selenium browser sessions. A simple interaction can navigate to a page and take a screenshot.

For exploratory testing, the planner workflow initializes a page, captures a snapshot, follows relevant links and flows, records discovered fields and validation behavior, and saves a Markdown test plan. The generator workflow initializes a page for a selected framework, records navigation and interaction steps, then writes the resulting test file.

Selenium Grid provides the parallel execution path. Instead of limiting work to one shared browser context, the server can use separate sessions and distribute activity across Grid nodes. This supports simultaneous exploration and running Chrome, Firefox, and Edge sessions together when the Grid is configured for those browsers.

## Setup and configuration

Install the package globally with:

```bash
npm install -g selenium-ai-agent
```

Alternatively, run it without a global installation:

```bash
npx selenium-ai-agent
```

Configure the MCP client to launch `npx selenium-ai-agent` over stdio. The project provides installation commands for Claude Desktop, Cursor, and Windsurf:

```bash
npx selenium-ai-agent install claude-desktop
npx selenium-ai-agent install cursor
npx selenium-ai-agent install windsurf
```

Claude Code can register it with:

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

Manual JSON examples use the `selenium-mcp` server name, `npx` as the command, and `selenium-ai-agent` as its argument. VS Code MCP configuration uses the same command with a `stdio` transport type. Generated projects may install their own framework dependencies, such as WebdriverIO, Playwright, Selenium, pytest, or a Python virtual environment.

## Tools and capabilities

- Navigate to web pages and capture screenshots.
- Interact with forms and page elements using text input, clicks, and visibility checks.
- Inspect pages through accessibility-tree snapshots.
- Explore application flows and save Markdown test plans.
- Record browser sessions and generate WebdriverIO, Playwright, or Selenium Python tests.
- Run isolated browser sessions in parallel through Selenium Grid.
- Support cross-browser execution with Chrome, Firefox, and Edge when available in the Grid.

## Limitations and notes

Parallel execution depends on a configured Selenium Grid and available browser nodes; the basic local setup launches the MCP process but does not by itself describe a Grid deployment. Generated tests can initialize project files and install framework dependencies, so those operations may modify the working directory and require the relevant package managers. Test plans should be reviewed before generating test code, especially when exploration covers application-specific flows and validation behavior.

_Full upstream README: https://allmcps.com/mcp/selenium-ai-agent/readme_