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

[![PyPI](https://img.shields.io/pypi/v/seleniumboot-mcp)](https://pypi.org/project/seleniumboot-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/seleniumboot-mcp)](https://pypi.org/project/seleniumboot-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/seleniumboot.selenium-boot-mcp?label=VS%20Code)](https://marketplace.visualstudio.com/items?itemName=seleniumboot.selenium-boot-mcp)
[![JetBrains Plugin](https://img.shields.io/jetbrains/plugin/v/32516?label=JetBrains)](https://plugins.jetbrains.com/plugin/32516)
[![JetBrains Downloads](https://img.shields.io/jetbrains/plugin/d/32516?label=downloads)](https://plugins.jetbrains.com/plugin/32516)

---

## Demo

▶ [Watch the demo on YouTube](https://youtu.be/54LoY2HNLrs)

---

## Installation

```bash
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](https://marketplace.visualstudio.com/items?itemName=seleniumboot.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](https://plugins.jetbrains.com/plugin/32516)** 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):

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

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

```json
{
  "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`

```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 (85 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 |
| `open_new_tab` | Open a new browser tab, optionally at a URL |
| `close_current_tab` | Close the active tab and switch to the previous |
| `list_windows` | List all open tabs with index, title, and URL |
| `close_browser` | Quit the browser |
| `scroll_to_top` | Scroll page to the top |
| `scroll_to_bottom` | Scroll page to the bottom |
| `scroll_by` | Scroll page by x/y pixels |
| `emulate_device` | Emulate a mobile device (iPhone, iPad, Pixel, Galaxy) via CDP |
| `get_console_logs` | Get browser console errors/warnings/info (Chrome) |
| `get_cookies` / `set_cookie` | Read or write a cookie |
| `delete_cookie` / `delete_all_cookies` | Remove cookies |
| `get_local_storage` / `set_local_storage` | Read or write localStorage |
| `get_session_storage` / `set_session_storage` | Read or write sessionStorage |
| `wait_for_network_idle` | Wait until XHR/fetch traffic is quiet — essential for SPAs |
| `inspect_page` | Discover all inputs, buttons, selects, links with best-fit CSS selectors |
| `get_network_logs` | Captured XHR/fetch requests — method, URL, status, timing |
| `mock_response` | Stub fetch/XHR by URL pattern with a canned response |
| `clear_mock_responses` | Remove all active mock rules |
| `compare_screenshot` | Pixel diff against a saved baseline — visual regression |
| `check_accessibility` | Built-in WCAG audit — alt text, labels, headings, keyboard access |

### 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 |
| `send_keys` | Send special keys (Tab, Enter, Escape, Ctrl+A, F5, …) |
| `upload_file` | Upload a file via `<input type="file">` |
| `accept_alert` / `dismiss_alert` | Handle JS alert/confirm dialogs |
| `get_alert_text` | Read the message from an alert |
| `type_in_alert` | Type into a JS prompt and accept |
| `switch_to_frame` | Focus into an iframe by index, name, or selector |
| `switch_to_default_content` | Return to the main page from a frame |
| `find_shadow_element` | Find element inside a shadow DOM |
| `get_table_data` | Extract an HTML table as a formatted text grid |
| `fill_form` | Fill multiple fields at once — auto-detects input/select/checkbox/radio |
| `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 |
| `generate_csharp_nunit` | C# NUnit + Selenium test class from session |
| `generate_github_actions` | GitHub Actions CI workflow YAML (Maven / Gradle / pytest) |
| `generate_jenkins_pipeline` | Declarative Jenkinsfile (Maven / Gradle / pytest) |
| `generate_gitlab_ci` | GitLab CI `.gitlab-ci.yml` pipeline (Maven / Gradle / pytest) |
| `generate_playwright_hints` | Equivalent Playwright TypeScript code 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
```

```java
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
```

```java
// 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
```

```gherkin
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
```

```java
// 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](https://seleniumboot.com) — 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:

| 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](https://github.com/seleniumboot/selenium-mcp)
- **PyPI:** [pypi.org/project/seleniumboot-mcp](https://pypi.org/project/seleniumboot-mcp/)
- **VS Code Marketplace:** [marketplace.visualstudio.com](https://marketplace.visualstudio.com/items?itemName=seleniumboot.selenium-boot-mcp)

---

## 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_java_page_object`)
- [x] Cucumber / Gherkin step generation (`generate_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