seleniumboot-mcp 0.1.2

A Python MCP server for Selenium WebDriver — browser automation and Java TestNG/JUnit5 codegen

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 / pytest test code from recorded sessions.

---

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:

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

Claude controls the real browser, records every action, and on request generates a complete test class with WebDriverWait, @BeforeMethod, @Test, @AfterMethod — ready to paste into your Maven or Gradle project.

---

Tools (37 total)

Browser

Tool	Description
start_browser	Start Chrome or Firefox (headless, window size)
navigate	Go to a URL
take_screenshot	Capture page as an 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

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	Generate Java TestNG class from session
generate_java_junit5	Generate Java JUnit 5 class from session
generate_python_test	Generate pytest class from session
get_session_log	View recorded actions
clear_session_log	Reset the session recording

---

Generated Java Example

After: navigate → fill form → click submit

package com.tests.selenium;

import org.openqa.selenium.*;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.interactions.Actions;
import org.openqa.selenium.support.ui.*;
import org.testng.annotations.*;
import java.time.Duration;

public class LoginTest {

    private WebDriver driver;
    private WebDriverWait wait;

    @BeforeMethod
    public void setUp() {
        driver = new ChromeDriver();
        driver.manage().window().maximize();
        wait = new WebDriverWait(driver, Duration.ofSeconds(10));
    }

    @AfterMethod
    public void tearDown() {
        if (driver != null) driver.quit();
    }

    @Test
    public void recordedFlowTest() {
        driver.get("https://app.example.com/login");
        WebElement field = wait.until(ExpectedConditions.visibilityOfElementLocated(By.cssSelector("#username")));
        field.clear();
        field.sendKeys("admin");
        WebElement pwd = wait.until(ExpectedConditions.visibilityOfElementLocated(By.cssSelector("#password")));
        pwd.clear();
        pwd.sendKeys("password");
        wait.until(ExpectedConditions.elementToBeClickable(By.cssSelector("button[type='submit']"))).click();
    }
}

---

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
• Cucumber / Gherkin step generation
• CI/CD config generator (GitHub Actions, Jenkins)
• Self-healing locators

---

License

MIT