Selenium MCP Setup: When Browser Automation Needs WebDriver
Choose Selenium MCP when you need local, cross-browser WebDriver control over Chrome, Firefox, Edge, or Safari. Start the stdio server, verify browser startup, and perform one read-only navigation. Only after that should you enable scripts, downloads, or authenticated sessions.
Choose Selenium MCP when you need local, cross-browser WebDriver control over Chrome, Firefox, Edge, or Safari. Start the stdio server, verify browser startup, and perform one read-only navigation. Only after that should you enable scripts, downloads, or authenticated sessions.
Table of contents
- When Selenium MCP is the right browser bridge
- Install Node, a browser, and its driver
- Connect the stdio server
- Verify navigation and element discovery
- Protect cookies, downloads, JavaScript, and signed-in profiles
- Fix driver, PATH, and session failures
- FAQ
When Selenium MCP is the right browser bridge
Selenium MCP is the right bridge when an AI agent needs to drive a real browser installed on your own machine through Selenium WebDriver. It supports Chrome, Firefox, Edge, and Safari, and exposes browser sessions, navigation, element interaction, screenshots, JavaScript, windows, frames, alerts, and cookies. Selenium WebDriver provides the browser-control foundation, while the Selenium MCP directory entry provides the practical MCP connection details.
Choose it when you need:
- Local end-to-end testing.
- Form filling in a browser you control.
- Scraping that depends on real browser behavior.
- Cross-browser checks across locally installed browsers.
- A browser bridge without an API key, account, or per-request billing.
Unlike cloud-browser MCP servers, mcp-selenium runs locally. That keeps the browser, driver, cookies, and resulting page access within the machine where the server runs.
It may be a poor fit when your workflow requires a hosted browser, a remote execution environment, or browser access without installing Node.js, a browser, and the relevant driver locally. The choice should follow the execution boundary: local WebDriver control points toward Selenium MCP; hosted browser infrastructure points elsewhere.
Install Node, a browser, and its driver
Install Node.js with npm, install a supported browser locally, and make its matching WebDriver available where needed. Chrome, Firefox, Edge, and Safari are supported; Safari requires macOS and additional one-time setup. Selenium’s WebDriver documentation explains the browser-driver model.
Before connecting the server, confirm these prerequisites:
-
Node.js and npm are available.
-
A supported browser is installed locally.
-
The matching WebDriver is available where needed, such as
chromedriverfor Chrome. -
For Safari, the machine runs macOS.
-
For Safari, run the one-time setup:
sudo safaridriver --enable -
In Safari settings, turn on Allow Remote Automation.
Safari does not provide a headless mode, so Safari sessions require a visible browser. The other setup details depend on the browser and operating system already present on the machine.
No API key or MCP account is required. Authentication for mcp-selenium is none, and the server runs through npx or a global npm installation. The browser automation capability page is a useful next step for comparing this local approach with other browser-control options.
Connect the stdio server
Connect the server over stdio with the verified npx instruction below:
npx -y @angiejones/mcp-selenium
The server uses stdio transport and has no authentication layer. Configure your MCP client to launch that command as its stdio server process; the exact configuration screen or field depends on the client. The MCP architecture documentation describes how clients and servers communicate through MCP transports.
Keep the connection configuration minimal during the first check. Start the server, confirm that the client recognizes it, and then inspect whether the browser-related resources and tools are available.
The package can also be installed globally with npm. One-line client commands are available for Claude Code and Goose, but the server command itself remains:
npx -y @angiejones/mcp-selenium
If the client reports that the server cannot start, first separate connection problems from browser problems. A client that never reaches the server indicates a stdio or Node/npm issue; a connected server that cannot create a browser session indicates a local browser or driver issue.
Verify navigation and element discovery
Verify the setup by starting a browser session, navigating to a non-sensitive page, and discovering an element without changing page data. The WebDriver standard defines the browser-control model behind these operations. (WebDriver standard)
Use this smoke test:
- Start a browser session.
- Check the current browser status.
- Navigate to a simple, read-only URL.
- Confirm that the page loads.
- Discover a visible element.
- Read its text or attributes.
- End the session.
Selenium MCP exposes the browser-status://current MCP resource for current browser status and accessibility://current for the current accessibility state. Use the accessibility resource when ordinary element discovery is unclear or when you need to understand the page structure before interacting with it.
Keep the first navigation deliberately simple. Avoid login pages, payment flows, file downloads, destructive buttons, and pages containing private account data. The goal is to prove three separate links in the chain:
- The MCP client can reach the stdio server.
- The server can create a WebDriver session.
- The browser can navigate and expose elements.
After that baseline succeeds, add one interaction at a time. The MCP server testing guide can help structure repeatable checks around startup, capability discovery, and expected results.
Protect cookies, downloads, JavaScript, and signed-in profiles
Treat Selenium MCP as local access to a real browser, including its cookies, page content, and browser controls. Keep the first run read-only, and enable JavaScript execution, downloads, cookies, or authenticated profiles only when the task requires them. (MCP security best practices)
A cautious sequence is:
- Verify startup with a clean browser context.
- Verify one read-only navigation.
- Discover elements without submitting forms.
- Enable JavaScript only for a page that needs it.
- Enable downloads only after confirming the destination and expected file.
- Use cookies or a signed-in profile only for a specifically authorized workflow.
JavaScript can change page state and interact with content that is not visible in the initial document. Downloads can create files on the local machine. Cookies and signed-in profiles can provide access to an account, so they should not be part of the initial smoke test.
Be especially careful with screenshots and page output. A screenshot or extracted element can contain account names, messages, order details, tokens, or other private content. Keep test URLs and browser results limited to the data needed for the task.
Selenium MCP also manages windows, frames, alerts, and cookies. These capabilities are useful for realistic browser workflows, but they increase the importance of confirming the target page, active window, and intended action before proceeding.
Fix driver, PATH, and session failures
Most startup failures come from one of three places: the MCP client cannot launch the stdio process, the browser driver is missing or not discoverable, or the browser session cannot be created. Check those layers separately, then use the server’s diagnostics tool when a session exists.
| Symptom | First check | Next action |
|---|---|---|
| The MCP client cannot connect | Node.js, npm, and the stdio command | Confirm the client launches npx -y @angiejones/mcp-selenium |
| The server connects but no browser starts | Supported browser installation | Confirm the browser is installed locally |
| A driver error appears | Matching WebDriver availability and PATH | Make the required driver discoverable to the server process |
| Safari will not start | macOS, Remote Automation, and Safari driver setup | Confirm sudo safaridriver --enable; remember Safari has no headless mode |
| The page loads but elements are missing | Navigation completion and page structure | Inspect accessibility://current and retry discovery |
| A session behaves unexpectedly | Current status and diagnostic output | Inspect browser-status://current and use the diagnostics tool |
The diagnostics tool is backed by WebDriver BiDi and can provide more context after a browser session is available. For configuration-specific problems, the MCP Config Doctor is a practical place to check the client-side setup.
Do not solve a driver failure by weakening TLS, authentication, or permission checks. Fix the local prerequisite, the stdio configuration, or the browser session state instead. The MCP debugging guide provides a structured way to isolate transport, capability, and runtime failures.