seleniumboot-mcp 0.2.3

A Python MCP server for Selenium WebDriver — browser automation, Java TestNG/JUnit5/Cucumber codegen, and Page Object Model generation

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. 45 tools. No ChromeDriver setup. Browser auto-starts on first use.

---

Installation

pip install seleniumboot-mcp

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

---

Setup

VS Code (Claude / Copilot)

Add .vscode/mcp.json to your project root:

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

Open the project in VS Code → click the Start button that appears above the config → 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.

---

Tools (45 total)

Browser

Tool	Description
start_browser	Optional — Chrome auto-starts on first use. Use this to pick Firefox, enable headless, or set window size
navigate	Go to a URL
take_screenshot	Capture page as an inline image
get_page_title	Return page title
get_current_url	Return current URL
get_page_source	Return full HTML source
execute_script	Run JavaScript
go_back / go_forward	Browser history
refresh	Reload page
switch_to_window	Switch between tabs by index
close_browser	Quit the browser

Elements

Tool	Description
find_element	Find element, return tag/text/state
find_elements	Find all matching elements
click	Click with explicit wait
type_text	Clear + type into input
get_text	Get visible text
get_attribute	Get any attribute value
select_option	Select from <select> by text, value, or index
hover	Mouse hover
double_click	Double click
right_click	Context menu click
drag_and_drop	Drag source → target
is_displayed	Check visibility
is_enabled	Check enabled state
wait_for_element	Wait: visible / clickable / present / invisible
scroll_to_element	Scroll element into view
clear_field	Clear input field
get_healed_locators	View all self-healed selector mappings for the session
clear_healed_locators	Reset the self-healing cache

Assertions

Tool	Description
assert_title	Page title equals/contains
assert_url	URL equals/contains
assert_text	Element text equals/contains
assert_element_visible	Element is visible
assert_element_not_visible	Element is hidden or absent
assert_attribute	Element attribute has expected value
assert_page_contains	Page body contains a string
assert_element_count	Count of matching elements equals expected

Codegen

Tool	Description
generate_java_testng	Java TestNG test class from session
generate_java_junit5	Java JUnit 5 test class from session
generate_java_page_object	Java Page Object class + test class from session
generate_gherkin	Gherkin .feature file + Java step definitions from session
generate_python_test	pytest class from session
get_session_log	View recorded actions
clear_session_log	Reset the session recording

---

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(); }
}

---

Self-Healing Locators

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

Primary selector	Alternatives tried
#my-id (CSS)	by=id "my-id", [id='my-id']
.my-class (CSS)	by=class "my-class", [class*='my-class']
input[type='email'] (CSS)	//input[@type='email'] (XPath)
//button[@id='ok'] (XPath)	button[id='ok'] (CSS), by=id "ok"
"A, B" comma list	tries A first, then B

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

---

Roadmap

• Java TestNG / JUnit 5 / Python pytest code generation
• Screenshot returned as ImageContent (renders inline in Claude)
• Full session recording — hover, double_click, right_click, scroll, select_option
• Codegen for hover, drag-and-drop, select, scroll in Java and Python templates
• Auto-start browser on first use (no explicit start_browser needed)
• Page Object Model generation (generate_java_page_object)
• Cucumber / Gherkin step generation (generate_gherkin)
• Self-healing locators — automatic fallback when a selector breaks
• CI/CD config generator (GitHub Actions, Jenkins)

---

License

MIT