seleniumboot/selenium-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.
43 tools by default (77 with SELENIUM_MCP_TOOLS=all). No ChromeDriver setup. Browser auto-starts on first use.
---
Demo
▶ Watch the demo on YouTube
---
Installation
> 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** 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** 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):
For Claude Code, add .mcp.json to your project root:
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
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:
Claude controls the real browser, records every action, and on request generates complete test code ready to paste into your Maven or Gradle project.
---
Migrating an existing Selenium project
The migrate tool runs selenium-boot-migrator's
read-only analyze on a project and returns its JSON report (what maps cleanly, what needs a human).
It needs Java 17+. On first use it downloads the pinned migrator release (v0.1.1) from GitHub
into ~/.cache/seleniumboot-mcp/, verifies its SHA-256, and reuses it afterwards; this is the only
network call the tool makes. To skip the download, set SELENIUM_BOOT_MIGRATOR_JAR to a jar you
built, or put a selenium-boot-migrator launcher on PATH. It never edits your project.
Tools (77 total; 43 exposed by default)
Reducing token use
Tool definitions are sent to the model every session. Since 0.8.0 the server exposes the
core profile by default: 43 tools, ~3.9k tokens, covering the record-and-generate workflow
(browser, elements, assertions, the single generate tool for every output target, and migrate).
Cookies, storage, windows/tabs, network mocking, device emulation, screenshot-diff,
accessibility, healing, shadow DOM, tables and double/right-click/drag are left out.
Set SELENIUM_MCP_TOOLS=all to expose all 77 (~6.4k tokens).
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 |