Back to Browse

Selenium Agent MCP Server

Search & WebLow Risk9.5MCP RegistryLocal
Free

Server data from the Official MCP Registry

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

About

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

Security Report

9.5
Low Risk9.5Low Risk

Valid MCP server (1 strong, 1 medium validity signals). 1 known CVE in dependencies Package registry verified. Imported from the Official MCP Registry.

12 files analyzed · 2 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

env_vars

Check that this permission is expected for this type of plugin.

Shell Command Execution

Runs commands on your machine. Be cautious — only use if you trust this plugin.

file_system

Check that this permission is expected for this type of plugin.

network_websocket

Check that this permission is expected for this type of plugin.

What You'll Need

Set these up before or after installing:

Run the browser in headless modeOptional

Environment variable: SELENIUM_HEADLESS

Tool groups to load: core, recording, planner, generator, healer, analyzer, grid or allOptional

Environment variable: SELENIUM_MCP_TOOLSETS

Selenium Grid hub URL, e.g. http://localhost:4444 (enables parallel execution)Optional

Environment variable: SELENIUM_GRID_URL

Attach to an already running Chrome at host:port, e.g. 127.0.0.1:9222Optional

Environment variable: SELENIUM_ATTACH_CDP

stdout returns data to the LLM; file saves screenshots and outputs to diskOptional

Environment variable: SELENIUM_MCP_OUTPUT_MODE

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "selenium-ai-agent": {
      "command": "npx",
      "args": [
        "-y",
        "selenium-ai-agent@3.5.0"
      ],
      "env": {
        "SELENIUM_GRID_URL": "your-selenium-grid-url-here",
        "SELENIUM_HEADLESS": "your-selenium-headless-here",
        "SELENIUM_ATTACH_CDP": "your-selenium-attach-cdp-here",
        "SELENIUM_MCP_TOOLSETS": "your-selenium-mcp-toolsets-here",
        "SELENIUM_MCP_OUTPUT_MODE": "your-selenium-mcp-output-mode-here"
      }
    }
  }
}

Some servers take additional arguments. See the repository for details.

Documentation

View on GitHub

From the project's GitHub README.

Selenium AI Agent

npm version License: MIT YouTube tutorials Selenium Grid

AI test agents for Selenium, like Playwright's: plan, generate and heal tests from a prompt.

Selenium AI Agent (selenium-ai-agent on npm) is an MCP server that lets your AI assistant drive a real browser through Selenium WebDriver and build a test suite for you.

  • Test agents: a planner explores your app and writes a structured test plan, a generator turns it into tests checked live in the browser, and a healer runs and repairs them.
  • Python + pytest by default, and any other language on request: Java, C#, JavaScript/TypeScript, WebdriverIO, Robot Framework.
  • Works in your AI client: Claude Code, Claude Desktop, VS Code (GitHub Copilot) and Cursor.
  • Built in Node.js: run it with npx -y selenium-ai-agent; the matching browser driver is downloaded for you.
  • Scales with Selenium Grid: parallel sessions on Chrome, Firefox and Edge.

Install in VS Code Install in VS Code Insiders Install in Cursor

Contents

Video Tutorials

Short demos with a voice-over, on YouTube:

Planner: from one prompt to a test planGenerator: from the plan to running pytest tests
Planner demoGenerator demo
The planner explores a web shop and writes specs/shopping-cart-and-checkout.md: 2 suites, 8 tests, 16 steps. (2:09)The generator writes one pytest file per plan test, runs them, and shows the HTML report, including a real bug it found. (1:44)

More tutorials: youtube.com/@ralphvanderhorst5193 · Practice site used in the demos: practiceautomatedtesting.com

Quick Start

You need Node.js 18+ and a browser (Chrome, Firefox or Edge).

1. Add the server to your AI client

Claude Code:

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

Claude Desktop, Cursor, Windsurf or Junie in IntelliJ IDEA / PyCharm (writes the config for you):

npx selenium-ai-agent install claude-desktop   # or: cursor, windsurf, junie

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json) and Cursor (.cursor/mcp.json):

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

VS Code / GitHub Copilot (.vscode/mcp.json):

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

IntelliJ IDEA / PyCharm with AI Assistant: Settings → Tools → AI Assistant → Model Context Protocol (MCP) → Add → As JSON, and paste the mcpServers JSON above. With GitHub Copilot in a JetBrains IDE: Settings → Tools → GitHub Copilot → Model Context Protocol (MCP) → Configure, and add the servers JSON above.

See MCP Client Setup and the package README for all clients, including Cline and Windsurf.

2. Install the test agents in your project (optional)

npx selenium-ai-agent init-agents --loop=claude    # Claude Code subagents
npx selenium-ai-agent init-agents --loop=vscode    # VS Code chat modes
npx selenium-ai-agent init-agents --loop=copilot   # GitHub Copilot coding agent
npx selenium-ai-agent init-agents --loop=cursor    # Cursor rules

Add --with-rules to also put Selenium's rules for AI agents in your project's CLAUDE.md, .cursor/rules/selenium.mdc or .github/copilot-instructions.md, so every AI tool you use writes modern Selenium code.

3. Ask for tests

Explore the shopping section of https://practiceautomatedtesting.com and create a test plan
for the shopping cart and checkout.

Then:

Generate Selenium tests from specs/shopping-cart-and-checkout.md, run them, and show me the test report.

Something not starting? Run npx selenium-ai-agent doctor.

How the Test Agents Work

┌─────────────────┐    ┌─────────────┐    ┌─────────────┐    ┌────────────┐
│    Analyzer     │───▶│   Planner   │───▶│  Generator  │───▶│   Healer   │
│  (risk profile) │    │ (test plan) │    │ (test code) │    │(fix tests) │
└─────────────────┘    └─────────────┘    └─────────────┘    └────────────┘
                             │                  │
                        human review       human review
AgentWhat it doesOutput
Analyzer (optional)Scans the product and builds a risk profile, so testing starts where it matters most.Risk profile
PlannerExplores the app in a real browser, takes an inventory of every page and pop-up, and writes a plan in the same structure as Playwright's planner: suites → tests → steps with expect. It adds the elements found (with stable locators) and the gaps.specs/<feature>.md
GeneratorWrites one test file per plan test, with an assertion for every expect, after checking each value live in the browser. Sets up the project (for Python: a virtual environment with Selenium and pytest) if needed.Test files, a run command
HealerRuns the tests, debugs failures, inspects the page and fixes broken locators or waits, then runs them again.Passing tests, or a clear bug report
MigratorUpgrades an existing suite to current Selenium 4: scans it for Selenium 3 patterns, sleeps and mixed waits (selenium_rules_check), runs it as a baseline, rewrites one file at a time and proves each still passes.Migrated tests, before/after results per file

The generator and healer follow Selenium's guide for AI agents (and WebdriverIO's for WebdriverIO): they read the current docs from llms.txt with get_selenium_docs, and refuse to write a test with a sleep, a driver path, DesiredCapabilities or a Selenium 3 API.

You review the plan before code is generated, and the code before it is committed. The Agent Workflow guide covers each stage in detail.

Example Prompts

GoalPrompt
Try itGo to https://practiceautomatedtesting.com and take a screenshot
Test planExplore the checkout flow at https://practiceautomatedtesting.com and create a test plan
Python tests (default)Generate tests from specs/checkout-flow.md
Another languageGenerate WebdriverIO tests for the login flow at https://practiceautomatedtesting.com
Fix failuresRun my tests and fix any failures
Parallel (Grid)Explore https://practiceautomatedtesting.com in parallel using 4 browsers

Example Chats shows each prompt with the tools it calls and the result, including generated code for pytest, WebdriverIO, Playwright and Robot Framework.

Languages and Frameworks

If you don't name one, the generator uses your project's own stack: Java with JUnit 5 or TestNG (from pom.xml or build.gradle), Python with pytest or unittest (requirements.txt, pyproject.toml, pytest.ini), C# with NUnit, xUnit or MSTest (*.csproj), JavaScript/TypeScript (package.json) or Robot Framework (*.robot). In an empty project it uses Python with pytest.

LanguageFrameworks (framework value)
Pythonpytest (selenium-python-pytest, default), unittest (selenium-python-unittest), Playwright (playwright-python), Robot Framework (robot-framework)
JavaMaven (selenium-java-maven), Gradle (selenium-java-gradle)
C#NUnit (selenium-csharp-nunit), MSTest (selenium-csharp-mstest), xUnit (selenium-csharp-xunit)
JavaScript / TypeScriptWebdriverIO (webdriverio-ts, webdriverio-js), Mocha (selenium-js-mocha), Jest (selenium-js-jest), Playwright (playwright-js)

Conventions per framework are in Framework Standards.

Parallel Testing with Selenium Grid

Everything above works with a local browser. Selenium Grid adds parallel sessions: explore or test many parts of an application at once, across Chrome, Firefox and Edge.

Playwright MCPSelenium AI Agent
ParallelismSingle browser, shared contextMany sessions on Grid nodes
ScalingLimited by one browserAdd nodes as needed
IsolationShared state between clientsFull isolation per session
Multi-browserOne at a timeChrome, Firefox and Edge at the same time

1. Start the Grid

git clone https://github.com/learn-automated-testing/selenium_agent.git
cd selenium_agent/selenium-grid
docker-compose up -d          # Grid console: http://localhost:4444

docker-compose up -d --scale chrome-node=10   # scale up any time

The included docker-compose.yml starts a hub, 4 Chrome nodes and 1 Firefox node.

2. Point the server at it

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

3. Explore in parallel

Explore https://practiceautomatedtesting.com in parallel: the homepage, products, cart and checkout at the same time.

parallel_explore starts one session per section, exploration_merge combines the results into one site map, and planner_generate_plan writes the test plan.

Configuration

VariableDefaultDescription
SELENIUM_GRID_URL—Grid hub URL; enables the parallel tools
SELENIUM_HEADLESSfalseRun the browser headless
SELENIUM_MCP_TOOLSETSallTool groups to load, e.g. core,generator,healer
SELENIUM_STEALTHfalseMask basic automation flags (does not get past advanced bot protection)
SE_AVOID_STATS—true disables Selenium usage statistics

All variables, CLI flags, driver and proxy setup, and troubleshooting are in the package README.

Tools

77 tools, 63 without Grid.

Test agents

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, selenium_rules_check
Analyzeranalyzer_setup, analyzer_import_context, analyzer_scan_product, analyzer_build_risk_profile, analyzer_save_profile, analyzer_generate_documentation

Browser

GroupTools
Navigationnavigate_to · go_back · go_forward · refresh_page
Page analysiscapture_page · take_screenshot
Elementsclick_element · hover_element · select_option · drag_drop
Inputinput_text · key_press · file_upload
Mousemouse_move · mouse_click · mouse_drag
Verificationverify_element_visible · verify_text_visible · verify_value · verify_list_visible
Browserwait_for · execute_javascript · dialog_handle · console_logs · network_monitor · resize_window · pdf_generate
Tabstab_list · tab_select · tab_new · tab_close
Sessionclose_browser · reset_session · set_stealth_mode
Recordingstart_recording · stop_recording · recording_status · clear_recording
Batchbatch_execute
Docsget_selenium_docs (current Selenium / WebdriverIO docs from their llms.txt)

Grid and parallel execution

ToolDescription
grid_statusCheck Grid health, nodes and capacity
grid_start / grid_stopStart or stop the Docker Compose Grid
grid_scaleScale Grid nodes up or down
session_create / session_select / session_listCreate, switch and list browser sessions on the Grid
session_destroy / session_destroy_allClean up one or all sessions
parallel_exploreExplore several URLs at the same time
parallel_executeRun tasks in parallel across sessions
exploration_merge / exploration_diffCombine or compare exploration results
planner_generate_planGenerate a test plan from an exploration

Documentation

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
│       └── tools/           # navigation, elements, grid, agents, analyzer
├── selenium-grid/
│   └── docker-compose.yml   # Selenium Grid setup
├── agents/                  # Agent prompt definitions
└── docs/                    # Guides and diagrams

Contributing

Contributions are welcome:

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

License

MIT — see LICENSE.

Acknowledgments


Reviews

No reviews yet

Be the first to review this server!