MCP Selenium Server

An MCP server that lets AI agents control a local Chrome browser via Java Selenium.

Prerequisites

• Node.js >= 18
• Java 17 (or higher)
• Maven
• Chrome installed; ensure compatible ChromeDriver is auto-managed by Selenium 4.x

Install

cd /Users/jai/MCP_Selenium
npm install
npm run java:build
npm run build

Run

• Headed (visible Chrome):

npm run dev

• Headless:

HEADLESS=true npm run dev

This starts the MCP server over stdio. Configure your AI client to launch node dist/server.js (or npm run dev during development) as an MCP tool server.

Publish as an npm CLI (optional)

This project can be published so projects can run with npx mcp-selenium-server.

1. Update version in package.json
2. Build artifacts:

npm run prepublishOnly

3. Login and publish:

npm login
npm publish --access public

Then in any project, create mcp.json:

{
  "name": "mcp-selenium-server",
  "version": "*",
  "command": { "args": ["npx", "mcp-selenium-server"] },
  "env": { "HEADLESS": "false" }
}

Tools exposed to agents

• navigate: { url } – Navigate to a URL.
• click: { selector } – Click an element matched by CSS selector.
• type: { selector, text } – Type text into an input/textarea/contenteditable.
• wait: { ms } – Wait milliseconds.
• screenshot: { path? } – Save screenshot to path (default screenshots/shot.png).

Agent context (provide to your model)

You are connected to an MCP server that controls a real Chrome browser on the user's machine using Selenium. Use the following tools to perform manual testing: navigate, click, type, wait, screenshot. Prefer robust CSS selectors. Confirm each step with a screenshot. After validating a flow manually, generate a Java Selenium JUnit test that reproduces the verified steps.

Safety: Avoid navigating to unsafe or unknown URLs. Do not download untrusted files. Ask the user before submitting forms with sensitive data.

Example manual flow

1. navigate { url: "https://example.com/login" }
2. type { selector: "#username", text: "demo" }
3. type { selector: "#password", text: "demoPass" }
4. click { selector: "button[type=submit]" }
5. wait { ms: 2000 }
6. screenshot { path: "screenshots/logged-in.png" }

Generating automation

After completing the manual flow, the agent should output a Java Selenium test skeleton (example):

// JUnit 5 test example
@Test
void login_flow() {
    ChromeOptions options = new ChromeOptions();
    WebDriver driver = new ChromeDriver(options);
    try {
        driver.get("https://example.com/login");
        driver.findElement(By.cssSelector("#username")).sendKeys("demo");
        driver.findElement(By.cssSelector("#password")).sendKeys("demoPass");
        driver.findElement(By.cssSelector("button[type=submit]")).click();
        new WebDriverWait(driver, Duration.ofSeconds(5))
            .until(d -> d.findElement(By.cssSelector(".dashboard")));
    } finally {
        driver.quit();
    }
}

Notes

• Selenium 4 auto-manages ChromeDriver; ensure Chrome is installed.
• Set HEADLESS=true for CI or background runs.
• Screenshots are stored relative to project root by default.