mcp-server-webdriver

MCP Server that lets AI agents control a real web browser via Selenium WebDriver (Firefox + geckodriver).
Built with FastMCP.

What it does

The server eliminates the copy-paste loop between the browser and the AI assistant. Instead of opening DevTools, copying errors, pasting them into a chat, and repeating, the assistant opens the browser itself, navigates, captures errors and screenshots, and diagnoses the problem directly.

You:  "Why is the checkout button broken on /cart?"

AI:   browser_open → browser_navigate("/cart")
      → devtools_report          # JS errors? network failures?
      → browser_screenshot       # what does it look like?
      → devtools_computed_css("button#checkout")   # hidden? wrong z-index?
      → "The button has pointer-events: none — overridden by .disabled class
         applied when cart.js fails to load (404 on /static/cart.js)."

Requirements

Installation

Recommended — Debian package from VitexSoftware repository

sudo curl -fsSL http://repo.vitexsoftware.com/KEY.gpg -o /usr/share/keyrings/vitexsoftware-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/vitexsoftware-archive-keyring.gpg] http://repo.vitexsoftware.com trixie main backports" \
  | sudo tee /etc/apt/sources.list.d/vitexsoftware.list
sudo apt update
sudo apt install mcp-server-webdriver

The backports component is required, not optional: python3-mcp (a python3-fastmcp dependency) needs python3-jsonschema >= 4.20.0, which is newer than the version Debian trixie ships in main — it's only available in backports. Without it, apt install fails with an unmet-dependency error on python3-jsonschema.

This installs gecko-driver, python3-selenium, python3-fastmcp, and mcp-server-webdriver in a single step.

Alternative — system package manager

# Debian/Ubuntu (official repos — may be older geckodriver):
sudo apt install firefox-geckodriver

# macOS:
brew install geckodriver

# Rust / cargo (build from source):
cargo install geckodriver

Then install Python dependencies:

pip install fastmcp selenium

Fallback — webdriver-manager (auto-download)

pip install fastmcp selenium webdriver-manager
# geckodriver is downloaded automatically on first browser_open call

Usage

mcp-server-webdriver [OPTIONS]

OPTIONS
  -P <profile>       Start Firefox with a named profile
  --profile <path>   Start Firefox with a profile directory at <path>
  -h, --help         Show help and exit

The server speaks MCP over stdin/stdout and is launched automatically by the MCP client — not by hand.

Use cases

Debug a broken page

Ask: "Why does /dashboard show a blank screen?"

The assistant will:

1. browser_open — open Firefox headlessly

2. browser_navigate — go to /dashboard

3. devtools_report — get JS errors, console output, and failed network resources in one call

4. browser_screenshot — see what the page actually looks like

5. Explain the root cause from the combined evidence

devtools_report is the primary diagnostic tool — equivalent to opening the Console and Network tabs in DevTools and reading them simultaneously.

Diagnose a CSS / layout problem

Ask: "The sidebar overlaps the content area on mobile. Why?"

1. browser_open — open the page

2. browser_screenshot — capture the broken layout

3. devtools_computed_css(".sidebar") — check position, width, z-index, overflow

4. devtools_css_variables("--") — verify design tokens loaded correctly

5. devtools_network_failed — check whether any stylesheet failed to load

Automate a login flow

Ask: "Log into the app at /login with user=admin, password=secret and screenshot the dashboard."

1. browser_open — start the browser

2. browser_navigate — go to /login

3. browser_fill("#username", "admin") — type username

4. browser_fill("#password", "secret") — type password

5. browser_press_key("enter") — submit the form

6. browser_wait("#dashboard", condition="visible") — wait for redirect

7. browser_screenshot — capture the result

Inject a session cookie to skip login

Ask: "Check the admin panel using my existing session token."

1. browser_open — start the browser

2. browser_navigate — go to the app's root so the cookie domain matches

3. browser_set_cookie("session", "<token>") — inject the auth cookie

4. browser_navigate — now navigate to the protected page

5. browser_screenshot — confirm access

Enumerate page content

Ask: "List all the navigation links on the homepage."

1. browser_open + browser_navigate — open the page

2. browser_find_elements("nav a") — get all links with their text, href, and visibility

3. Return the structured list

Interact with hover menus

Ask: "Click the third item in the Products dropdown."

1. browser_hover(".nav-products") — trigger the :hover state that reveals the dropdown

2. browser_wait(".dropdown-menu", condition="visible") — wait for animation

3. browser_find_elements(".dropdown-menu a") — list the items

4. browser_click(".dropdown-menu a:nth-child(3)") — click the right one

Test a multi-step form

Ask: "Fill out the registration form and submit it."

1. browser_fill("#first-name", "Alice")

2. browser_fill("#last-name", "Smith")

3. browser_fill("#email", "alice@example.com")

4. browser_select("#country", "Czech Republic")

5. browser_press_key("tab") — move focus to next field

6. browser_click("button[type=submit"]")

7. browser_wait(".success-message", condition="visible")

8. devtools_report — check for any JS errors or failed API calls during submission

Handle JS dialogs

Ask: "Click the Delete button and confirm the dialog."

1. browser_click("#delete-btn")

2. browser_accept_dialog — click OK on the confirm("Are you sure?")

3. browser_wait(".deleted-notice", condition="present")

Scroll and capture a long page

Ask: "Screenshot the footer of the page."

1. browser_open + browser_navigate

2. browser_scroll("footer") — scroll the footer element into view

3. browser_screenshot("footer") — capture just the footer element

Or scroll by offset to trigger lazy-loaded content:

1. browser_scroll(by=True, y=1000) — scroll down 1000 px

2. browser_wait(".lazy-section", condition="visible") — wait for lazy content

3. browser_screenshot — capture the now-loaded content

Use a real Firefox profile (stay logged in)

Configure the server with a named profile that already has your session:

{
  "mcpServers": {
    "webdriver": {
      "command": "mcp-server-webdriver",
      "args": ["-P", "work"]
    }
  }
}

The browser starts with your existing cookies, saved passwords, and extensions. Ask: "Check my GitHub notifications." — no login step needed.

Profile selection is intentionally a server-launch-time setting (-P/--profile flags or FIREFOX_PROFILE/FIREFOX_PROFILE_DIR env vars) rather than a browser_open tool parameter. That keeps the choice to expose a real, logged-in profile to an agent in the hands of whoever configures the MCP client — not something an agent (or a prompt injected via a visited page) can request at runtime.

Audit network performance

Ask: "Which resources on /shop are slowest to load?"

1. browser_open + browser_navigate("/shop")

2. devtools_network_all(slow_ms=500, limit=20) — requests over 500 ms, capped at 20 entries

3. Report the slowest assets with their URLs, types, and durations

Available Tools

Session management

Navigation

Page inspection

Interaction

Dialogs & cookies

DevTools (require BiDi — Firefox + geckodriver ≥ 0.34)

Security

Anything a visited page contains — HTML, visible text, attribute values, console output, JS error messages, web storage — is attacker-controllable if the page is malicious or compromised. Tools that relay this content back to the calling agent (browser_get_source, browser_get_text, browser_get_attribute, devtools_console, devtools_js_errors, devtools_report, browser_get_storage) wrap it in an explicit -----BEGIN/END UNTRUSTED CONTENT----- envelope (or an untrusted field on structured entries), so an agent has a structural signal that the content is data to read, never an instruction to follow — even if it's phrased as one. This defends against indirect prompt-injection / agent-hijacking attacks delivered via ordinary page content.

This complements the existing Firefox-profile lockdown (see Use a real Firefox profile): both exist because a page — or an instruction injected via one — should never be able to silently expand what the agent can do or see.

The server also defaults to read-only mode: page-mutating tools (browser_click, browser_fill, browser_upload_file, browser_select, browser_execute_js, browser_press_key, browser_accept_dialog, browser_dismiss_dialog, browser_set_cookie, browser_set_storage, browser_clear_storage) refuse to run unless WEBDRIVER_READONLY=false is set. Navigation and session/viewport management (browser_open, browser_navigate, browser_back/forward/refresh, browser_scroll, browser_hover, browser_wait, browser_switch_frame, browser_close, browser_set_viewport) are unaffected, since they're needed to reach the page a read-only session inspects.

Environment variables

geckodriver resolution order

MCP client configuration

Minimal config:

{
  "mcpServers": {
    "webdriver": {
      "command": "mcp-server-webdriver"
    }
  }
}

With a named Firefox profile (stays logged in, uses saved passwords):

{
  "mcpServers": {
    "webdriver": {
      "command": "mcp-server-webdriver",
      "args": ["-P", "work"]
    }
  }
}

With a profile directory and explicit geckodriver path:

{
  "mcpServers": {
    "webdriver": {
      "command": "mcp-server-webdriver",
      "args": ["--profile", "/home/user/.mozilla/firefox/abc123.dev"],
      "env": {
        "GECKODRIVER_PATH": "/usr/bin/geckodriver"
      }
    }
  }
}

Running tests

# Unit tests only (no browser required):
pytest tests/ -m "not integration"

# All tests including browser integration:
pytest tests/

Related MCP Servers by VitexSoftware

License

MIT