# seleniumboot/selenium-mcp [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/seleniumboot/selenium-mcp  
**GitHub Stars:** 2  
**Views:** 11  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/seleniumboot-selenium-mcp

## Description
Python MCP server for Selenium WebDriver — 84 tools for browser automation, element interactions, assertions, and self-healing locators, plus codegen for Java TestNG / JUnit 5 / Cucumber / pytest / C NUnit / Playwright and CI pipelines (GitHub Actions / Jenkins / GitLab CI). No ChromeDriver setup needed.

## Tools
Capabilities this server exposes over MCP:

- **start_browser** — Start a browser session. Optional — any tool will auto-start Chrome if no browser is open. Use this to choose Firefox, enable headless mode, or set a custom window size.
- **navigate** — Navigate the browser to a URL.
- **take_screenshot** — Take a screenshot and return it as base64.
- **get_page_source** — Return the current page HTML source.
- **get_page_title** — Return the current page title.
- **get_current_url** — Return the current URL.
- **close_browser** — Close and quit the browser session.
- **go_back** — Navigate back in browser history.
- **go_forward** — Navigate forward in browser history.
- **refresh** — Refresh the current page.
- **execute_script** — Execute JavaScript in the browser.
- **switch_to_window** — Switch to a browser window/tab by index.
- **open_new_tab** — Open a new browser tab, optionally navigating to a URL.
- **close_current_tab** — Close the currently active tab and switch to the previous one.
- **list_windows** — List all open browser tabs/windows with their index, title, and URL.
- **scroll_to_top** — Scroll the page to the very top.
- **scroll_to_bottom** — Scroll the page to the very bottom.
- **scroll_by** — Scroll the page by a given number of pixels (positive = down/right).
- **emulate_device** — Emulate a mobile device using Chrome DevTools Protocol. Adjusts viewport, pixel ratio, and touch.
- **get_console_logs** — Return browser console logs (errors, warnings, info). Chrome only.
- **get_cookies** — Return all cookies for the current page, or a single cookie by name.
- **set_cookie** — Set a cookie on the current page.
- **delete_cookie** — Delete a specific cookie by name.
- **delete_all_cookies** — Delete all cookies for the current session.
- **get_local_storage** — Get a value from localStorage, or return all keys if no key is given.
- **set_local_storage** — Set a localStorage key-value pair.
- **get_session_storage** — Get a value from sessionStorage, or return all keys if no key is given.
- **set_session_storage** — Set a sessionStorage key-value pair.
- **inspect_page** — Discover all interactive elements on the current page — inputs, buttons, selects, checkboxes, textareas, and links — with their best CSS selectors and labels. Use this before writing locators so the AI knows exactly what's on the page.
- **get_network_logs** — Return captured XHR/fetch network requests (method, URL, status, timing). Chrome only.
- **mock_response** — Intercept fetch/XHR requests matching a URL pattern and return a canned response. Useful for testing without a real backend. Injection survives until the page is reloaded.
- **clear_mock_responses** — Remove all active mock response rules injected by mock_response.
- **compare_screenshot** — Compare the current page screenshot against a saved baseline. On first run (or with update_baseline=true) saves the baseline. Returns the pixel diff percentage. Install Pillow for accurate pixel comparison.
- **check_accessibility** — Run a built-in accessibility audit on the current page. Checks for missing alt text, unlabelled inputs, empty buttons/links, missing page title, HTML lang, heading structure, and keyboard accessibility.
- **wait_for_network_idle** — Wait until there are no active XHR/fetch requests for a quiet period. Essential for SPAs and pages that load data asynchronously. Also waits for document.readyState to be 'complete'.
- **find_element** — Find an element and return its text, tag, and attributes.
- **find_elements** — Find all matching elements and return their texts.
- **click** — Click on an element.
- **type_text** — Clear and type text into an input field.
- **get_text** — Get the visible text content of an element.
- **get_attribute** — Get an attribute value from an element.
- **select_option** — Select an option from a <select> dropdown by visible text, value, or index.
- **hover** — Hover the mouse over an element.
- **double_click** — Double-click on an element.
- **right_click** — Right-click (context menu) on an element.
- **drag_and_drop** — Drag one element and drop it onto another.
- **is_displayed** — Check if an element is visible on the page.
- **is_enabled** — Check if an element is enabled (not disabled).
- **wait_for_element** — Wait until an element is visible on the page.
- **scroll_to_element** — Scroll the page to bring an element into view.
- **clear_field** — Clear the text in an input field.
- **fill_form** — Fill multiple form fields in a single call. Pass a map of CSS selector → value. Automatically handles text inputs, textareas, checkboxes (true/false), radio buttons, and <select> dropdowns. Optionally clicks a submit button at the end.
- **get_healed_locators** — Return all self-healed locator mappings from this session. Shows which selectors were automatically repaired and what they were replaced with.
- **clear_healed_locators** — Clear the self-healing locator cache so all selectors are re-evaluated from scratch.
- **accept_alert** — Accept (OK) a JavaScript alert, confirm, or prompt dialog.
- **dismiss_alert** — Dismiss (Cancel) a JavaScript confirm or prompt dialog.
- **get_alert_text** — Return the text message of a currently open JavaScript alert/confirm/prompt.
- **type_in_alert** — Type text into a JavaScript prompt dialog, then accept it.
- **switch_to_frame** — Switch focus into an iframe. Provide index (integer), name/id (string), or a CSS/XPath selector.
- **switch_to_default_content** — Switch back to the main page content from inside a frame.
- **send_keys** — Send a key or key combination to the focused element (or a specific element if selector is given). Use key names like 'tab', 'enter', 'escape', 'up', 'down', 'f5', or combos like 'ctrl+a', 'shift+tab'.
- **upload_file** — Upload a file by sending its absolute path to an <input type='file'> element.
- **find_shadow_element** — Find an element inside a shadow DOM. Provide the host element selector and then the selector for the element inside the shadow root.
- **get_table_data** — Extract data from an HTML table as a formatted text grid.
- **assert_title** — Assert the page title equals or contains expected text.
- **assert_url** — Assert the current URL equals or contains expected value.
- **assert_text** — Assert element text equals or contains expected value.
- **assert_element_visible** — Assert an element is visible on the page.
- **assert_element_not_visible** — Assert an element is NOT visible (hidden or absent).
- **assert_attribute** — Assert an element attribute has the expected value.
- **assert_page_contains** — Assert the full page source or visible text contains a string.
- **assert_element_count** — Assert number of elements matching selector equals expected count.
- **generate_python_test** — Generate a pytest + Selenium test script from the current browser session. Captures all recorded actions (navigate, click, type, hover, drag, select, etc.) into a runnable test.
- **generate_java_testng** — Generate a Java TestNG test class from the current browser session. framework='testng' (default) emits standalone Selenium with a ChromeDriver setUp/tearDown; framework='selenium_boot' emits a Selenium Boot test (extends BaseTest, framework-managed driver, accessibility-first getByRole/getByLabel/getByTestId locators and web-first assertThat assertions — no driver lifecycle boilerplate). In a Selenium Boot project, use framework='selenium_boot'.
- **generate_java_junit5** — Generate a Java JUnit 5 test class from the current browser session. framework='junit5' (default) emits standalone Selenium with a ChromeDriver setUp/tearDown; framework='selenium_boot' emits a Selenium Boot test (extends BaseJUnit5Test, framework-managed driver, accessibility-first locators and web-first assertThat assertions). In a Selenium Boot project, use framework='selenium_boot'.
- **detect_selenium_boot** — Detect whether the current working directory is inside a Selenium Boot project (looks for selenium-boot.yml or the io.github.seleniumboot dependency in pom.xml / build.gradle, walking up parent directories). Call this BEFORE generating Java code: if it reports detected=true, generate with framework="selenium_boot" so the output uses the framework's accessibility-first locators and managed driver.
- **get_session_log** — Return the raw list of recorded actions in the current session.
- **clear_session_log** — Clear the recorded action log and start fresh.
- **generate_gherkin** — Generate a Cucumber Gherkin .feature file + Java step definitions class from the recorded browser session. Steps are written in plain English and wired to Java code. framework='raw' (default) emits standalone Selenium with a ChromeDriver @Before/@After; framework='selenium_boot' emits steps extending BaseCucumberSteps with framework-managed driver and accessibility-first locators. Use 'selenium_boot' in a Selenium Boot project.
- **generate_csharp_nunit** — Generate a C# NUnit + Selenium test class from the current browser session.
- **generate_github_actions** — Generate a GitHub Actions CI workflow YAML for running the recorded test session.
- **generate_jenkins_pipeline** — Generate a declarative Jenkinsfile for running the recorded test session (Maven, Gradle, or pytest).
- **generate_gitlab_ci** — Generate a .gitlab-ci.yml pipeline for running the recorded test session (Maven, Gradle, or pytest).
- **generate_playwright_hints** — Generate equivalent Playwright (TypeScript) code hints from the recorded browser session.
- **generate_java_page_object** — Generate a Java Page Object class + matching test class from the recorded session. USE THIS INSTEAD OF WRITING JAVA BY HAND — the output compiles as-is and contains only the elements/actions actually performed, so it never invents fields or uses non-existent framework APIs. Produces two files: a Page Object (locators + fluent action methods) and a Test class that uses it. Supports raw Selenium (TestNG / JUnit 5) and the Selenium Boot framework (selenium_boot): Page Object extends BasePage, Test extends BaseTest, no manual driver lifecycle — the framework manages it — with accessibility-first locators. For any Java test in a Selenium Boot repo, use framework="selenium_boot".

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "selenium-mcp": {
    "command": "uvx",
    "args": ["seleniumboot-mcp"]
  }
}
```

## Documentation

## What seleniumboot/selenium-mcp does

seleniumboot/selenium-mcp exposes Selenium WebDriver through the Model Context Protocol for browser automation. An MCP client can open a browser, visit URLs, inspect page structure, interact with controls, run JavaScript, and verify application state. The server is aimed at workflows where an AI agent needs to operate a real browser rather than make direct HTTP requests.

It can also record the actions performed during a session and generate automation artifacts from them. Supported output targets include Java TestNG, JUnit 5, Cucumber, pytest, C NUnit, Playwright, and CI pipeline configurations for GitHub Actions, Jenkins, and GitLab CI.

## How it works

The server communicates with MCP clients over stdio and delegates browser control to Selenium WebDriver. Chrome launches automatically when the first browser tool is used, although `start_browser` can select Firefox, enable headless mode, or set a custom window size. Selenium Manager handles the browser driver, so a separate ChromeDriver installation is not required.

Page discovery is available through `inspect_page`, which reports interactive controls and suggested CSS selectors. The server also provides explicit waits, locator self-healing, screenshots, page source, console output, cookies, web storage, window and tab control, network capture, device emulation, and JavaScript execution. Chrome-only functions include console logs, network logs, and Chrome DevTools Protocol device emulation.

The default tool profile exposes the core record-and-generate workflow. Setting `SELENIUM_MCP_TOOLS=all` enables the broader tool set, including storage, network mocking, accessibility checks, screenshot comparison, shadow DOM, table extraction, advanced mouse actions, and healing-related tools.

## Setup and configuration

Install the Python package with:

```bash
pip install seleniumboot-mcp
```

Python 3.10 or newer and Chrome are required. A minimal stdio configuration for an MCP client is:

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

The project also provides setup paths through its VS Code extension and JetBrains plugin. The VS Code extension registers the server with GitHub Copilot and can create a project `.mcp.json` for Claude Code. The JetBrains plugin registers it with JetBrains AI Assistant. Claude Desktop can use the same command in its MCP configuration.

Use `SELENIUM_MCP_TOOLS=all` when the client needs the complete tool collection instead of the default core profile. The optional `migrate` capability requires Java 17 or newer and analyzes an existing Selenium project without modifying it.

## Tools and capabilities

Core browser operations include:

- Start, close, refresh, and navigate browser sessions.
- Move through browser history and manage multiple tabs or windows.
- Capture screenshots, page source, titles, URLs, console logs, and network activity.
- Inspect controls, find elements, fill forms, click, type, hover, select options, upload files, and handle alerts.
- Switch into iframes, access shadow DOM elements, scroll pages, and execute JavaScript.
- Read and update cookies, localStorage, and sessionStorage.
- Wait for elements or network activity and perform visibility, title, URL, text, and attribute assertions.
- Emulate mobile devices and generate test code from recorded actions.

## Limitations and notes

The default profile exposes fewer tools than the full collection to reduce the tool definitions sent to the model. Chrome-specific features do not provide the same behavior in Firefox. Browser sessions and their state are controlled by the running server process, so a client must remain connected while an agent performs a flow. The migration tool is read-only, requires Java 17+, and downloads its migrator artifact on first use unless a local launcher or JAR is configured.

_Full upstream README: https://allmcps.com/mcp/seleniumboot-selenium-mcp/readme_