Selenium MCP

seleniumboot-mcp

A Python Model Context Protocol (MCP) server for Selenium WebDriver automation. Let Claude or GitHub Copilot control a real browser — navigate pages, interact with elements, run assertions, and generate ready-to-run Java TestNG / JUnit 5 / Cucumber / pytest test code from recorded sessions. 43 tools by default (77 with SELENIUM_MCP_TOOLS=all). No ChromeDriver setup. Browser auto-starts on first use.

---

Demo

▶ Watch the demo on YouTube

---

Installation

pip install seleniumboot-mcp

Requires Python 3.10+ and Chrome. No separate ChromeDriver needed — Selenium Manager handles it automatically.

---

Setup

VS Code — Marketplace Extension (easiest)

Install Selenium Boot MCP from the VS Code Marketplace.

The extension automatically:

• Registers the MCP server with GitHub Copilot (no config file needed)
• Creates a .mcp.json in your project so Claude Code detects it on next open
• Prompts to pip install seleniumboot-mcp if the Python package is missing

When Claude Code asks "Allow MCP server seleniumboot?" — click Allow.

JetBrains IDEs — Marketplace Plugin

Install Selenium Boot MCP from Settings → Plugins → Marketplace (search "Selenium Boot MCP"), or from the plugin page.

The plugin registers the MCP server with the JetBrains AI Assistant and prompts to pip install seleniumboot-mcp if the Python package is missing. Use Tools → Selenium Boot MCP to install/upgrade, register, or check status.

VS Code — Manual

Add .vscode/mcp.json to your project root (for GitHub Copilot):

{
  "servers": {
    "selenium": {
      "type": "stdio",
      "command": "seleniumboot-mcp"
    }
  }
}

For Claude Code, add .mcp.json to your project root:

{
  "mcpServers": {
    "seleniumboot": {
      "command": "seleniumboot-mcp",
      "args": []
    }
  }
}

Open the project in VS Code → Claude Code will prompt to approve the server → done.

Claude Desktop

Edit your Claude Desktop config:

• Windows: %APPDATA%\claude-desktop\config.json
• macOS: ~/.config/claude-desktop/config.json

{
  "mcpServers": {
    "selenium": {
      "command": "seleniumboot-mcp"
    }
  }
}

Restart Claude Desktop.

---

How to use

Once the server is running, talk to Claude naturally — no start_browser call needed, Chrome launches automatically on first use:

Go to https://myapp.com and fill the login form with admin/password, then click Login

Assert the dashboard heading is visible

Generate a Java TestNG test class for everything we just did

Generate a Gherkin feature file and step definitions for the login flow

Claude controls the real browser, records every action, and on request generates complete test code ready to paste into your Maven or Gradle project.

---

Migrating an existing Selenium project

The migrate tool runs selenium-boot-migrator's read-only analyze on a project and returns its JSON report (what maps cleanly, what needs a human). It needs Java 17+. On first use it downloads the pinned migrator release (v0.1.1) from GitHub into ~/.cache/seleniumboot-mcp/, verifies its SHA-256, and reuses it afterwards; this is the only network call the tool makes. To skip the download, set SELENIUM_BOOT_MIGRATOR_JAR to a jar you built, or put a selenium-boot-migrator launcher on PATH. It never edits your project.

Tools (77 total; 43 exposed by default)

Reducing token use

Tool definitions are sent to the model every session. Since 0.8.0 the server exposes the core profile by default: 43 tools, ~3.9k tokens, covering the record-and-generate workflow (browser, elements, assertions, the single generate tool for every output target, and migrate). Cookies, storage, windows/tabs, network mocking, device emulation, screenshot-diff, accessibility, healing, shadow DOM, tables and double/right-click/drag are left out. Set SELENIUM_MCP_TOOLS=all to expose all 77 (~6.4k tokens).

{ "mcpServers": { "selenium": { "command": "seleniumboot-mcp", "env": { "SELENIUM_MCP_TOOLS": "all" } } } }

Browser

Elements

Assertions

Codegen

---

Codegen Examples

Java TestNG

Go to https://myapp.com/login, enter admin/password, click Login
→ Generate a Java TestNG test

public class LoginTest {
    @BeforeMethod public void setUp() { driver = new ChromeDriver(); ... }
    @AfterMethod  public void tearDown() { driver.quit(); }

    @Test
    public void recordedFlowTest() {
        driver.get("https://myapp.com/login");
        WebElement f = wait.until(visibilityOf(By.cssSelector("#username")));
        f.clear(); f.sendKeys("admin");
        wait.until(elementToBeClickable(By.cssSelector("button[type='submit']"))).click();
    }
}

Page Object Model

Generate a Java Page Object for the login page

// LoginPage.java
public class LoginPage {
    private final By usernameField = By.cssSelector("#username");
    private final By submitButton  = By.cssSelector("button[type='submit']");

    public LoginPage enterUsernameField(String text) { ... return this; }
    public LoginPage clickSubmitButton()              { ... return this; }
}

// LoginTest.java
public class LoginTest {
    @Test public void recordedFlowTest() {
        driver.get("https://myapp.com/login");
        page.enterUsernameField("admin").clickSubmitButton();
    }
}

Cucumber / Gherkin

Generate a Gherkin feature file and step definitions for the login flow

Feature: Login

  Scenario: User logs in with valid credentials
    Given I navigate to "https://myapp.com/login"
    And I enter "admin" in the username field
    And I enter "password" in the password field
    And I click the submit button

// LoginSteps.java
public class LoginSteps {
    @Given("I navigate to {string}")
    public void iNavigateTo(String url) { driver.get(url); }

    @And("I enter {string} in the username field")
    public void iEnterInUsernameField(String text) { ... el.sendKeys(text); }

    @And("I click the submit button")
    public void iClickTheSubmitButton() { wait.until(...).click(); }
}

Selenium Boot projects

The Java examples above are raw Selenium: you own the ChromeDriver/WebDriverWait lifecycle and get plain TestNG/JUnit 5 asserts. If the project you're working in has Selenium Boot — detected automatically from selenium-boot.yml or the io.github.seleniumboot dependency, no flag needed — the same tools emit framework-native code instead: classes extend BaseTest/BaseJUnit5Test/BaseCucumberSteps, there's no driver lifecycle boilerplate to write, locators follow an accessibility-first ladder (getByRole/getByLabel/getByTestId), and assertions are web-first (assertThat(locator).isVisible()/.hasText()) instead of raw TestNG/JUnit calls.

If no Selenium Boot project is detected, generated Java now includes a short comment noting it as an option, with a link — nothing else changes, and Python/C# output is unaffected either way.

---

Self-Healing Locators

When a selector fails to find an element, seleniumboot-mcp automatically tries alternative strategies before giving up:

Successful fallbacks are cached so the healed selector is reused automatically. Use get_healed_locators to inspect the cache and update your test code, and clear_healed_locators to start fresh.

---

Links

• GitHub: github.com/seleniumboot/selenium-mcp
• PyPI: pypi.org/project/seleniumboot-mcp
• VS Code Marketplace: marketplace.visualstudio.com

---

Roadmap

• [x] Java TestNG / JUnit 5 / Python pytest code generation
• [x] Screenshot returned as ImageContent (renders inline in Claude)
• [x] Full session recording — hover, double_click, right_click, scroll, select_option
• [x] Codegen for hover, drag-and-drop, select, scroll in Java and Python templates
• [x] Auto-start browser on first use (no explicit start_browser needed)
• [x] Page Object Model generation (generate with language=java, kind=page_object)
• [x] Cucumber / Gherkin step generation (generate with language=gherkin)
• [x] Self-healing locators — automatic fallback when a selector breaks
• [x] Alert/dialog handling, iframe switching, shadow DOM, table extraction
• [x] Cookie, localStorage, sessionStorage management
• [x] Mobile device emulation via Chrome DevTools Protocol
• [x] Special key sending (Tab, Enter, F-keys, Ctrl+A, …)
• [x] File upload via <input type="file">
• [x] Browser console log capture
• [x] Multi-tab management (open, close, list)
• [x] Page scroll (top, bottom, by pixels)
• [x] C# NUnit + Selenium codegen
• [x] GitHub Actions CI workflow generator (Maven / Gradle / pytest)
• [x] Playwright TypeScript migration hints
• [x] CI/CD config for Jenkins / GitLab CI

---

License

MIT