Selenium MCP

What selenium-mcp MCP server does

The selenium-mcp MCP server exposes real-browser automation through the Model Context Protocol. It connects MCP clients to Selenium WebDriver and supports Chrome, Firefox, and Edge. Selenium Manager provisions the matching browser driver automatically when a supported browser is installed.

Its 41 tools cover the browser lifecycle, navigation, page inspection, user interactions, assertions, scripting, cookies, windows, frames, alerts, screenshots, and session management. Agents can open a browser, navigate to a URL, inspect the current page, interact with elements, verify results, and close the session without writing a separate automation script.

The server also exposes two MCP resources: browser-status://current for live browser and session status, and accessibility://current for an accessibility snapshot of the current page.

How it works

A typical workflow starts a browser session, navigates to a page, captures the page or finds an element, performs an action, and checks the result. capture_page produces a page snapshot with stable element references that later actions can use. This gives agents a structured view of the page before they click, type, select, or scroll.

Multiple browser sessions can be created, selected, listed, and destroyed. That supports parallel or separate browser contexts when one workflow must not reuse another session. batch_execute can run constrained multi-step sequences in one MCP call, reducing the number of agent round trips.

The implementation uses TypeScript, the official MCP SDK, Selenium WebDriver, strict Zod input validation, explicit waits, and structured responses. Tools include waits for elements, URLs, and page titles, which helps workflows handle redirects and dynamically rendered content.

Setup and configuration

The selenium-mcp MCP server requires Node.js 20 or newer and an installed Chrome, Firefox, or Edge browser. The package can be launched through npx:

{
  "mcpServers": {
    "selenium": {
      "command": "npx",
      "args": ["-y", "@gaforov/selenium-mcp@latest"]
    }
  }
}

Claude Code can add it with claude mcp add selenium -- npx -y @gaforov/selenium-mcp@latest. VS Code supports code --add-mcp with the same command and package arguments. JetBrains IDEs can add an MCP entry using npx and those arguments. From source, clone the repository, run npm install and npm run build, then point the client to dist/server.js.

Tracing is optional. Set SELENIUM_MCP_TRACE=true to enable NDJSON logging of tool calls. SELENIUM_MCP_TRACE_PATH changes the trace file location; without it, logs are written to logs/selenium-mcp-trace.ndjson.

Tools and capabilities

The selenium-mcp MCP server includes tools for:

• Starting, stopping, creating, selecting, listing, and destroying browser sessions
• Navigating, using back/forward/refresh, waiting for a URL or title, and reading the current URL or title
• Finding elements, waiting for visibility, capturing page snapshots, and retrieving page source
• Clicking, retrying clicks, hovering, double-clicking, right-clicking, typing, selecting options, scrolling, pressing keys, and uploading files
• Reading text and attributes, taking screenshots, and running JavaScript
• Asserting text, visibility, and attributes
• Managing tabs, windows, viewport size, frames, alerts, and cookies
• Saving, retrieving, listing, and deleting per-domain selector hints

Selector hints persist working locators by domain. Assertions and structured validation provide explicit results and errors for agent workflows.

Limitations and notes

This server controls installed desktop browsers rather than a browserless API. A compatible browser and Node.js 20+ are prerequisites.

SELENIUM_MCP_TRACE and SELENIUM_MCP_TRACE_PATH are optional configuration variables, not startup requirements. The project is licensed under MIT. The current release notes identify open_url and wait_until_visible as removed duplicates; use navigate and wait_for_element with visible: true instead.