Selenium AI Agent

Registre officiel IA et agents

Selenium MCP: plan, generate and heal tests; pytest by default, any language; Selenium Grid

Installation

Ajoutez ceci à la configuration MCP de votre client (Claude Desktop : claude_desktop_config.json ; Cursor : .cursor/mcp.json ; VS Code et les autres utilisent la même forme « mcpServers »).

NPM package selenium-ai-agent
Claude Code
claude mcp add selenium-ai-agent -e 'SELENIUM_HEADLESS=false' -e 'SELENIUM_MCP_TOOLSETS=all' -e 'SELENIUM_GRID_URL=<SELENIUM_GRID_URL>' -e 'SELENIUM_ATTACH_CDP=<SELENIUM_ATTACH_CDP>' -e 'SELENIUM_MCP_OUTPUT_MODE=stdout' -- npx -y selenium-ai-agent@3.8.0
Configuration JSON (Claude Desktop, Cursor, VS Code)
{
    "mcpServers": {
        "selenium-ai-agent": {
            "command": "npx",
            "args": [
                "-y",
                "selenium-ai-agent@3.8.0"
            ],
            "env": {
                "SELENIUM_HEADLESS": "false",
                "SELENIUM_MCP_TOOLSETS": "all",
                "SELENIUM_GRID_URL": "<SELENIUM_GRID_URL>",
                "SELENIUM_ATTACH_CDP": "<SELENIUM_ATTACH_CDP>",
                "SELENIUM_MCP_OUTPUT_MODE": "stdout"
            }
        }
    }
}

Variables d'environnement

  • SELENIUM_HEADLESS Run the browser in headless mode
  • SELENIUM_MCP_TOOLSETS Tool groups to load: core, recording, planner, generator, healer, analyzer, grid or all
  • SELENIUM_GRID_URL Selenium Grid hub URL, e.g. http://localhost:4444 (enables parallel execution)
  • SELENIUM_ATTACH_CDP Attach to an already running Chrome at host:port, e.g. 127.0.0.1:9222
  • SELENIUM_MCP_OUTPUT_MODE stdout returns data to the LLM; file saves screenshots and outputs to disk

Documentation

Tirée du README du projet sur GitHub, actualisée chaque semaine. Les liens ouvrent GitHub.

Sommaire
  1. Selenium MCP Server
  2. Why This Over Playwright MCP?
  3. Quick Start
  4. Example Chats
  5. Parallel Exploration with Selenium Grid
  6. 75 Tools (61 without Grid)
  7. AI Test Agents
  8. Configuration
  9. Docker Compose
  10. Project Structure
  11. Documentation
  12. Contributing
  13. License
  14. Acknowledgments

Selenium MCP Server

One-Click Install

The first MCP server with true parallel browser automation using Selenium Grid.

While other browser MCP servers run a single browser instance, Selenium MCP Server connects to Selenium Grid for massive parallel exploration — spin up 10, 20, or 100 browser sessions and explore your entire application simultaneously.

Why This Over Playwright MCP?

FeaturePlaywright MCPSelenium MCP Server
ParallelismSingle browser, shared contextTrue parallel: Grid with unlimited nodes
ScalingLimited by single browserHorizontally scalable — add nodes as needed
IsolationShared state between clientsFull isolation per session
Multi-browserOne at a timeChrome + Firefox + Edge simultaneously
InfrastructureSimpleDocker Compose ready
AI Agent workflowsBasicPlanner → Generator → Healer pipeline

Perfect for: AI agents that need to explore large applications fast, cross-browser testing, and enterprise automation at scale.

Quick Start

1. Install
# Install globally
npm install -g selenium-ai-agent

# Or run directly with npx (no install needed)
npx selenium-ai-agent
2. Configure Your MCP Client

Auto-install (Claude Desktop, Cursor, or Windsurf):

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

Claude Code:

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

Manual config (click to expand)

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

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

Cursor (.cursor/mcp.json):

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

GitHub Copilot (.vscode/mcp.json):

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

See MCP Client Setup for all 6 clients (Claude Code, Claude Desktop, Cursor, Copilot, Cline, Windsurf).

3. Try It!
"Navigate to https://example.com and take a screenshot"

Example Chats

Copy-paste these prompts into your AI assistant after configuring the MCP server.

Navigate & Screenshot

You say:

Go to https://practiceautomatedtesting.com and take a screenshot

What happens:

  1. navigate_to — opens the URL in a local Chrome browser
  2. take_screenshot — captures the full page

AI responds:

I navigated to practiceautomatedtesting.com and took a screenshot. The page shows an e-commerce storefront with a navigation bar, featured products section, and a footer.


Explore & Create Test Plan

You say:

Explore the checkout flow at https://practiceautomatedtesting.com and create a test plan

What happens:

  1. planner_setup_page — navigates to the site, captures the initial page snapshot
  2. planner_explore_page — explores the homepage, discovers links to products
  3. planner_explore_page — follows the product → add-to-cart → cart page flow
  4. planner_explore_page — continues through checkout, captures form fields and validation
  5. planner_save_plan — writes the test plan to a markdown file

AI responds:

I explored the checkout flow across 4 pages and saved a test plan to test-plans/checkout-flow.md. The plan covers 6 test scenarios including add to cart, checkout form validation, and successful order. Please review the plan before I generate test code.


Generate WebdriverIO Tests

You say:

Generate WebdriverIO tests for the login flow at https://practiceautomatedtesting.com

What happens:

  1. Initializes the project if needed — npm init, installs @wdio/cli, creates wdio.conf.ts
  2. generator_setup_page — opens the site with framework: "webdriverio-ts", starts recording
  3. navigate_to → input_text → click_element → verify_text_visible — interacts with the login form
  4. stop_recording — ends the recording session
  5. generator_write_test — generates a .test.ts file from the recorded steps

AI responds:

I set up a WebdriverIO project, recorded the login flow, and generated tests/login.test.ts:

describe('Login Flow', () => {
  it('should log in with valid credentials', async () => {
    await browser.url('https://practiceautomatedtesting.com/login');
    await $('[data-testid="email"]').setValue('user@example.com');
    await $('[data-testid="password"]').setValue('password123');
    await $('[data-testid="login-button"]').click();
    await expect($('[data-testid="welcome-message"]')).toBeDisplayed();
  });
});

Run with: npx wdio run wdio.conf.ts


Generate Playwright Tests

You say:

Create Playwright tests for the product search feature at https://practiceautomatedtesting.com

What happens:

  1. Initializes the project if needed — npm init, installs @playwright/test, runs npx playwright install
  2. generator_setup_page — opens the site with framework: "playwright-js", starts recording
  3. Navigates and interacts with the search feature
  4. stop_recording → generator_write_test — generates a Playwright test file

AI responds:

I set up a Playwright project, recorded the search flow, and generated tests/product-search.spec.js:

const { test, expect } = require('@playwright/test');

test('should search for products and display results', async ({ page }) => {
  await page.goto('https://practiceautomatedtesting.com/products');
  await page.locator('[data-testid="search-input"]').fill('laptop');
  await page.locator('[data-testid="search-button"]').click();
  await expect(page.locator('[data-testid="results-count"]')).toBeVisible();
});

Run with: npx playwright test


Generate Selenium Python (pytest) Tests

You say:

Generate pytest Selenium tests for the registration form at https://practiceautomatedtesting.com

What happens:

  1. Sets up the project if needed — creates venv, installs selenium and pytest via pip
  2. generator_setup_page — opens the site with framework: "selenium-python-pytest", starts recording
  3. Navigates and fills in the registration form
  4. stop_recording → generator_write_test — generates a pytest file

AI responds:

I set up a Python virtual environment with selenium and pytest, recorded the registration flow, and generated tests/test_registration.py:

class TestRegistration:
    def test_register_new_user(self, driver):
        driver.get("https://practiceautomatedtesting.com/register")
        driver.find_element(By.CSS_SELECTOR, '[data-testid="name"]').send_keys("Jane Doe")
        driver.find_element(By.CSS_SELECTOR, '[data-testid="email"]').send_keys("jane@example.com")
        driver.find_element(By.CSS_SELECTOR, '[data-testid="password"]').send_keys("SecurePass123!")
        driver.find_element(By.CSS_SELECTOR, '[data-testid="register-button"]').click()
        assert "Welcome" in WebDriverWait(driver, 10).until(
            EC.visibility_of_element_located((By.CSS_SELECTOR, '[data-testid="success-message"]'))
        ).text

Run with: pytest tests/test_registration.py -v


Generate Robot Framework Tests

You say:

Generate Robot Framework tests for the contact form at https://practiceautomatedtesting.com

What happens:

  1. Sets up the project if needed — creates venv, installs robotframework and robotframework-seleniumlibrary via pip
  2. generator_setup_page — opens the site with framework: "robot-framework", starts recording
  3. Navigates to the contact page and fills in the form
  4. stop_recording → generator_write_test — generates a .robot file

AI responds:

I set up a Robot Framework environment, recorded the contact form flow, and generated tests/contact_form.robot:

*** Settings ***
Library    SeleniumLibrary

*** Variables ***
${URL}    https://practiceautomatedtesting.com/contact

*** Test Cases ***
Submit Contact Form With Valid Data
    Open Browser    ${URL}    chrome
    Input Text    css=[data-testid="name"]    Jane Doe
    Input Text    css=[data-testid="email"]    jane@example.com
    Input Text    css=[data-testid="message"]    Hello, I have a question about your products.
    Click Element    css=[data-testid="submit-button"]
    Wait Until Element Is Visible    css=[data-testid="success-message"]
    Element Should Contain    css=[data-testid="success-message"]    Thank you
    [Teardown]    Close Browser

Run with: robot tests/contact_form.robot


Run Tests & Heal Failures

You say:

Run my tests and fix any failures

What happens:

  1. healer_run_tests — executes the test suite; 1 of 3 tests fails
  2. healer_debug_test — analyzes the failure (stale selector #old-login-btn not found)
  3. healer_inspect_page — opens the page to find the correct selector
  4. healer_fix_test — updates the selector to [data-testid="login-button"]
  5. healer_run_tests — re-runs the suite; all 3 tests pass

AI responds:

I ran your test suite and found 1 failure: selector #old-login-btn not found. I inspected the page, updated it to [data-testid="login-button"], and re-ran — 3 passed, 0 failed.


Parallel Grid Exploration

Requires Grid setup.

You say:

Explore the entire site at https://practiceautomatedtesting.com in parallel using 4 browsers

What happens:

  1. parallel_explore — spins up 4 Grid sessions exploring Homepage, Products, Cart, and Account simultaneously
  2. exploration_merge — combines all 4 results into a single site map
  3. planner_generate_plan — produces a comprehensive test plan from the merged data

AI responds:

I explored the site in parallel using 4 browsers on your Selenium Grid:

SessionSectionPagesElements
1Homepage342
2Products8156
3Cart & Checkout467
4Account & Auth338

18 unique pages, 303 elements discovered in ~12 seconds. Test plan saved to test-plans/full-site-plan.md.


The Generator supports 14 frameworks: webdriverio-ts, playwright-js, selenium-python-pytest, robot-framework, selenium-java-maven, and more. Examples 1–6 work with a local browser. Only parallel exploration requires Selenium Grid.

Parallel Exploration with Selenium Grid

Explore your entire application in seconds, not minutes:

Start the Grid
git clone https://github.com/learn-automated-testing/selenium_agent.git
cd selenium_agent/selenium-grid
docker-compose up -d

# Verify Grid is running
open http://localhost:4444  # Grid console
Configure with Grid
{
  "mcpServers": {
    "selenium-mcp": {
      "command": "npx",
      "args": ["selenium-ai-agent"],
      "env": {
        "SELENIUM_GRID_URL": "http://localhost:4444"
      }
    }
  }
}
Explore in Parallel
"Explore the e-commerce site at https://practiceautomatedtesting.com in parallel —
check the homepage, products, cart, and checkout sections simultaneously"

The agent will spin up 4 browser sessions on your Grid and explore all sections at once.

// What happens behind the scenes:
parallel_explore({
  baseUrl: "https://myshop.com",
  targets: [
    { url: "/", label: "Homepage", maxPages: 10 },
    { url: "/products", label: "Catalog", maxPages: 20 },
    { url: "/cart", label: "Cart Flow", maxPages: 5 },
    { url: "/account", label: "User Account", maxPages: 10 }
  ]
})
// → 4 browsers explore simultaneously
// → Results merged and deduplicated
// → Complete site map in one call

Scale up anytime:

docker-compose up -d --scale chrome-node=10

75 Tools (61 without Grid)

Grid & Parallel Execution
ToolDescription
grid_statusCheck Grid health, nodes, and capacity
grid_startStart Docker Compose Grid
grid_stopStop Docker Compose Grid
grid_scaleScale Grid nodes up/down
session_createCreate browser session on Grid
session_selectSwitch active session
session_listList all Grid sessions
session_destroyClean up a session
session_destroy_allClean up all sessions
parallel_exploreExplore multiple URLs simultaneously
parallel_executeRun tasks in parallel across sessions
exploration_mergeCombine exploration results
exploration_diffCompare explorations
planner_generate_planGenerate test plan from exploration
Navigation

navigate_to · go_back · go_forward · refresh_page

Page Analysis

capture_page · take_screenshot

Element Interactions

click_element · hover_element · select_option · drag_drop

Input

input_text · key_press · file_upload

Mouse

mouse_move · mouse_click · mouse_drag

Verification

verify_element_visible · verify_text_visible · verify_value · verify_list_visible

Browser Management

wait_for · execute_javascript · dialog_handle · console_logs · network_monitor · resize_window · pdf_generate

Tabs

tab_list · tab_select · tab_new · tab_close

Session

close_browser · reset_session · set_stealth_mode

Recording

start_recording · stop_recording · recording_status · clear_recording

Batch

batch_execute

AI Agent Tools
AgentTools
Plannerplanner_setup_page, planner_explore_page, planner_save_plan
Generatorgenerator_setup_page, generator_read_log, generator_write_test, generator_write_seed, generator_save_spec, generator_read_spec
Healerhealer_run_tests, healer_debug_test, healer_fix_test, healer_inspect_page, browser_generate_locator
Analyzeranalyzer_setup, analyzer_import_context, analyzer_scan_product, analyzer_build_risk_profile, analyzer_save_profile, analyzer_generate_documentation

AI Test Agents

A complete testing pipeline with human review gates:

┌─────────────────┐    ┌─────────────┐    ┌─────────────┐    ┌────────────┐
│    Analyzer     │───▶│   Planner   │───▶│  Generator  │───▶│   Healer   │
│  (risk profile) │    │ (test plan) │    │ (test code) │    │(fix tests) │
└─────────────────┘    └─────────────┘    └─────────────┘    └────────────┘
                             │                  │
                        human review       human review

See Example Chats above for full copy-paste prompts covering each stage.

Configuration

Environment Variables
VariableDefaultDescription
SELENIUM_GRID_URL—Grid hub URL (enables parallel features)
SELENIUM_HEADLESSfalseRun browser in headless mode
SELENIUM_MCP_TOOLSETSallComma-separated tool groups to load, e.g. core,generator,healer (see the package README)
SELENIUM_STEALTHfalseMask basic automation flags (does not get past advanced bot protection)
SE_AVOID_STATS—Set to true to disable Selenium usage statistics
Local Browser (No Grid)

Works without Grid — just don't set SELENIUM_GRID_URL:

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

Docker Compose

The included docker-compose.yml gives you a production-ready Grid:

services:
  selenium-hub:
    image: selenium/hub:4.40.0
    ports:
      - "4444:4444"

  chrome-node:
    image: selenium/node-chrome:4.40.0
    deploy:
      replicas: 4  # 4 Chrome browsers

  firefox-node:
    image: selenium/node-firefox:4.40.0
    deploy:
      replicas: 1  # 1 Firefox browser

Project Structure

selenium_agent/
├── selenium-mcp-server/     # TypeScript MCP server (npm: selenium-ai-agent)
│   └── src/
│       ├── server.ts        # MCP protocol handler
│       ├── context.ts       # Browser session management
│       ├── grid/            # Selenium Grid integration
│       │   ├── grid-client.ts
│       │   ├── session-pool.ts
│       │   └── exploration-coordinator.ts
│       └── tools/           # 75 tools
│           ├── navigation/
│           ├── elements/
│           ├── grid/        # Parallel execution tools
│           ├── agents/      # AI agent tools
│           └── analyzer/    # Risk analysis
│
├── selenium-grid/
│   └── docker-compose.yml   # Selenium Grid setup
├── agents/                  # Agent prompt definitions
└── docs/                    # Guides and diagrams

Documentation

Contributing

Contributions welcome! Please read our contributing guidelines and submit PRs.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

MIT — see LICENSE for details.

Acknowledgments


If this project helps you, please give it a star!

Star on GitHub

Questions fréquentes

Qu'est-ce que Selenium AI Agent ?

Selenium MCP: plan, generate and heal tests; pytest by default, any language; Selenium Grid

Comment installer Selenium AI Agent ?

Il s'exécute sur votre machine. Dans Claude Code : claude mcp add selenium-ai-agent -e 'SELENIUM_HEADLESS=false' -e 'SELENIUM_MCP_TOOLSETS=all' -e 'SELENIUM_GRID_URL=<SELENIUM_GRID_URL>' -e 'SELENIUM_ATTACH_CDP=<SELENIUM_ATTACH_CDP>' -e 'SELENIUM_MCP_OUTPUT_MODE=stdout' -- npx -y selenium-ai-agent@3.8.0. Pour les autres clients, collez la configuration JSON de cette page dans leurs réglages MCP.

Faut-il une clé API pour Selenium AI Agent ?

Son entrée au registre n'indique aucune clé ni secret obligatoire. Certaines fonctions peuvent tout de même demander un compte auprès du service auquel il se connecte.

Selenium AI Agent est-il open source ?

Oui. Son code est sur GitHub sous licence MIT.

Qui maintient Selenium AI Agent ?

Il est publié par learn-automated-testing. AI.tn le référence sans le maintenir ni le recommander.

Issu du registre MCP officiel. Être listé n'est pas une recommandation : vérifiez le code et les permissions d'un serveur avant de lui donner accès à vos données.