Selenium MCP

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:

pip install seleniumboot-mcp

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

{
  "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.