Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
There is no single official “Selenium Java MCP Server.” The phrase describes a category of community MCP (Model Context Protocol) servers that let an AI client call browser tools implemented with Selenium WebDriver, while a Java project supplies page objects, assertions, test runners, and Maven execution. Before installing anything, identify the repository, license, release, transport, supported Java version, and AI client for the server you intend to use.
This guide shows a practical Java 11+ architecture, a safe evaluation process, a minimal Maven/TestNG project, MCP configuration patterns, CI considerations, and recovery steps. The examples deliberately keep the server adapter abstract because projects such as PhungXuanAnh/selenium-mcp-server, seleniumboot/selenium-mcp, and simple-mcp-selenium are separate community implementations rather than interchangeable packages.
What a Selenium Java MCP server actually does
MCP is the integration boundary between an AI agent and browser automation. The agent sends a tool call such as “open this URL” or “click the sign-in button”; the MCP server translates that call into Selenium WebDriver operations. Selenium controls Chrome, Firefox, or another supported browser. Your Java test code still owns page objects, assertions, fixtures, reporting, and build execution.
Recommended Free Tools
That separation matters. An MCP server does not replace WebDriver, TestNG, Cucumber, Maven, or your CI system. It adds an agent-controlled interface on top of them. The server may expose navigation, element interaction, DOM inspection, screenshots, assertions, locator repair, or code-generation tools, but capabilities differ by repository.
Why the title is ambiguous
Community directories list several Selenium MCP projects, including PhungXuanAnh/selenium-mcp-server, seleniumboot/selenium-mcp, and simple-mcp-selenium. No authoritative source establishes one canonical Maven coordinate, release version, or official Java server. Treat every listing as a candidate until you verify it.
Repository checks before installation
- Confirm the repository owner, license, recent commits, release process, and open-issue response.
- Check the required Java runtime, Selenium version, browser versions, and operating systems.
- Verify whether the server is a standalone process, a Java library, or a wrapper around another language runtime.
- Confirm MCP transport (usually stdio or HTTP) and compatibility with your client, such as Claude, Cursor, or another MCP host.
- Look for examples that compile and identify the exact tool names and arguments.
Recommended Java architecture
A maintainable setup has four layers:
- AI client: receives the user’s natural-language task and issues MCP calls.
- MCP server: validates tool arguments and maps them to WebDriver actions.
- Browser session: Selenium 4.x controls a deterministic Chrome or Firefox instance.
- Java test project: Maven builds the code; TestNG or Cucumber supplies tests, assertions, and reports.
A commonly described stack is Selenium 4.x, Java 11+, Maven, TestNG or Cucumber, and an MCP server acting as the bridge between the agent and WebDriver. Pin all versions in CI instead of relying on whatever browser happens to be installed.
Build a baseline Java Selenium project
1. Create the Maven project
Use this dependency pattern, then adjust Selenium and TestNG versions to the versions supported by your selected server and build environment.
<project>
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>selenium-mcp-demo</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
<maven.compiler.release>11</maven.compiler.release>
<selenium.version>4.x.x</selenium.version>
<testng.version>7.x.x</testng.version>
</properties>
<dependencies>
<dependency>
<groupId>org.seleniumhq.selenium</groupId>
<artifactId>selenium-java</artifactId>
<version>${selenium.version}</version>
</dependency>
<dependency>
<groupId>org.testng</groupId>
<artifactId>testng</artifactId>
<version>${testng.version}</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.2.5</version>
</plugin>
</plugins>
</build>
</project>Replace the illustrative 4.x.x and 7.x.x values with concrete versions approved by your project; do not copy an unverified version from a random MCP repository.
Rank #2
2. Add a deterministic WebDriver fixture
package com.example;
import java.time.Duration;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import org.testng.annotations.AfterMethod;
import org.testng.annotations.BeforeMethod;
public abstract class WebTest {
protected WebDriver driver;
@BeforeMethod
public void startBrowser() {
ChromeOptions options = new ChromeOptions();
if (Boolean.getBoolean("headless")) {
options.addArguments("--headless=new", "--window-size=1440,1000");
}
driver = new ChromeDriver(options);
driver.manage().timeouts().implicitlyWait(Duration.ofSeconds(5));
driver.manage().timeouts().pageLoadTimeout(Duration.ofSeconds(60));
}
@AfterMethod(alwaysRun = true)
public void stopBrowser() {
if (driver != null) driver.quit();
}
}Use explicit waits for important state changes; implicit waits alone can hide synchronization defects. In CI, install a pinned browser image or use a Selenium Grid rather than downloading an uncontrolled driver at runtime.
3. Add a page object and test
package com.example;
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.support.ui.ExpectedConditions;
import org.openqa.selenium.support.ui.WebDriverWait;
import java.time.Duration;
public final class ExamplePage {
private final WebDriver driver;
private final WebDriverWait wait;
public ExamplePage(WebDriver driver) {
this.driver = driver;
this.wait = new WebDriverWait(driver, Duration.ofSeconds(15));
}
public void open(String url) { driver.get(url); }
public String title() { return driver.getTitle(); }
public void click(By locator) {
wait.until(ExpectedConditions.elementToBeClickable(locator)).click();
}
}package com.example;
import org.testng.Assert;
import org.testng.annotations.Test;
public class SmokeTest extends WebTest {
@Test
public void pageLoads() {
ExamplePage page = new ExamplePage(driver);
page.open("https://example.com");
Assert.assertFalse(page.title().isBlank());
}
}Run it with mvn test. Run headless with mvn -Dheadless=true test. This baseline is valuable even when an agent drives exploratory steps: it gives you a reproducible test and a place to preserve generated code.
Connect an MCP server to an AI client
Exact configuration keys depend on the client and repository. Most stdio servers are launched as a command with arguments and environment variables. A generic configuration shape is:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
{
"mcpServers": {
"selenium-java": {
"command": "java",
"args": ["-jar", "/absolute/path/to/verified-server.jar"],
"env": {
"BROWSER": "chrome",
"HEADLESS": "true"
}
}
}
}Use the server’s published command, not this placeholder path. If the implementation is a Python or Node process that controls a Java Selenium Grid, configure that runtime instead and document the boundary. Start with one browser session and one tool call. Confirm that the client can list tools, open a harmless page, inspect the DOM, and quit the session before granting access to authenticated systems.
Prompts that produce safer automation
- Specify the target URL, expected state, and allowed side effects.
- Ask the agent to inspect before clicking, and to report the locator it selected.
- Require confirmation before submitting forms, deleting data, or making purchases.
- Ask it to save generated Java code into your repository rather than treating a chat transcript as a test artifact.
How to compare Selenium MCP implementations
| Axis | Questions to answer |
|---|---|
| Maintenance | Are commits, releases, issue handling, license, and supported runtimes clear? |
| Tool surface | Does it provide navigation, element actions, assertions, screenshots, DOM inspection, or code generation? |
| Java integration | Are Maven coordinates, Java examples, TestNG/Cucumber adapters, and Selenium compatibility documented? |
| Client and transport | Does it support your MCP client and required stdio or HTTP transport? |
| Browser lifecycle | Can it manage Chrome/Firefox, headless mode, profiles, driver versions, and parallel sessions? |
| CI/CD | Are containers, secrets, deterministic browsers, logs, screenshots, and artifacts practical? |
Directory descriptions mention capabilities such as assertions, self-healing locators, and Java/Python/C# generation for some projects. Do not assume those features exist in every server; verify each tool schema.
CI, reliability, and security
Make runs reproducible
- Pin Java, Maven, browser, driver, Selenium, and server versions.
- Use isolated profiles and a separate test account; never expose production credentials to an agent.
- Capture browser logs, screenshots, page source, and the MCP request that preceded a failure.
- Limit parallelism until session cleanup is proven. Always quit drivers in an
alwaysRunteardown. - Set explicit page-load and script timeouts, then fail with a useful diagnostic rather than retrying indefinitely.
Handle agent-specific risks
MCP tools can turn natural-language instructions into real browser actions. Restrict allowed domains, redact secrets from logs, validate URLs, and require human approval for irreversible operations. Treat generated locators and assertions as code requiring review.
Troubleshooting
The client cannot start the server
Check the absolute executable or JAR path, Java version, working directory, permissions, and required environment variables. Run the exact command in a terminal first and inspect stderr. A transport mismatch (stdio configured while the server expects HTTP) produces the same symptom.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesNo tools appear in the client
Confirm that the process completed MCP initialization and that the client uses the server’s actual configuration key. Upgrade or downgrade only after checking the server’s compatibility notes; tool names are implementation-specific.
Rank #4
Chrome starts locally but fails in CI
Use a browser image with matching versions, add the CI-required headless and sandbox flags, and verify display and filesystem permissions. Save the browser and driver versions in the job log.
Elements are intermittently missing
Replace fixed sleeps with explicit waits for visibility, clickability, or a specific DOM condition. Check whether a cookie banner, iframe, shadow root, or asynchronous navigation changes the locator context.
Generated tests are brittle
Prefer stable data attributes, page objects, and assertions about user-visible outcomes. Review every locator and remove accidental coordinates or timing assumptions before committing.
Free tools Windows power users keep installed
One-click scans. No signup required.
Or skip the browser setup
If your goal is a clean image or PDF rather than interactive Selenium testing, ScreenshotNeo provides a one-call website screenshot API. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. It also offers an MCP server with take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
See the ScreenshotNeo API documentation for options such as full-page lazy-image capture, CSS-selector element shots, dark mode, device presets, retina scale, PDF paper and page ranges, custom CSS/JavaScript, clicks, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, TTL caching, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting, and OpenAPI support.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.
Best Value
Choosing a practical path
Choose an MCP server only after its repository and compatibility are verified. Use the Java project for durable tests, assertions, and CI; use MCP for agent-guided exploration and controlled actions. If you only need deterministic page images or PDFs, an API can remove browser-driver maintenance entirely.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Frequently Asked Questions
Is Selenium Java MCP Server an official Selenium product?
No. The name refers to a category of community MCP integrations; no single canonical repository or Maven artifact is established.
Can an MCP server generate Java Selenium tests?
Some implementations advertise code-generation tools, but support is not universal. Verify the server’s tool schema and review generated code before use.
Should MCP replace TestNG or Cucumber?
No. MCP supplies an agent-facing control layer, while TestNG or Cucumber continues to organize scenarios, assertions, fixtures, and reports.
Which transport should a Java team choose?
Use the transport supported by both your selected server and AI client. Stdio is usually simplest for a local process; HTTP can suit a shared service but requires authentication and network controls.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
