Skip to main content
Glama
mcp-server-webdriver

mcp-server-webdriver

mcp-server-webdriver

mcp-server-webdriver License: MIT Packaging: deb

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)."

Related MCP server: Selenium MCP Server

Requirements

Dependency

Version

Python

≥ 3.11

FastMCP

≥ 2.10

selenium

≥ 4.0

Firefox

any recent

geckodriver

≥ 0.34


Installation

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


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

Tool

Description

browser_open

Open Firefox (URL optional, default about:blank); accepts width, height, user_agent for mobile emulation

browser_close

Quit the browser session

browser_status

Session state, geckodriver version, BiDi status, current viewport size, buffer counts

browser_set_viewport

Resize the viewport mid-session (e.g. 390×844 for iPhone 14)

Navigation

Tool

Description

browser_navigate

Navigate to a URL (bare hostnames get https://)

browser_back

Go back in history

browser_forward

Go forward in history

browser_refresh

Reload the current page

Page inspection

Tool

Description

browser_screenshot

Full-page or element PNG screenshot

browser_get_title

Current page <title>

browser_get_url

Current URL

browser_get_source

Raw HTML source (wrapped as untrusted content — see Security)

browser_get_text

Visible text (whole page or CSS selector; wrapped as untrusted content)

browser_get_attribute

Value of an HTML attribute on an element (wrapped as untrusted content)

browser_find_elements

List all elements matching a CSS selector

Interaction

Tool

Description

browser_click

Click element (CSS selector)

browser_fill

Type text into an input field (clears first by default)

browser_select

Select <option> in a <select> dropdown

browser_execute_js

Run JavaScript — returns JSON

browser_wait

Wait: visible / clickable / present / text:<str>

browser_scroll

Scroll to coords, by offset, or element into view

browser_press_key

Send enter / tab / escape / arrow / F-keys

browser_hover

Hover mouse over element (:hover states, tooltips, dropdowns)

browser_switch_frame

Switch into <iframe> or back to main document

Dialogs & cookies

Tool

Description

browser_accept_dialog

Accept a JS alert() / confirm() / prompt()

browser_dismiss_dialog

Dismiss a JS confirm() / prompt()

browser_get_cookies

Read all cookies for the current page

browser_set_cookie

Inject a cookie (auth tokens, session IDs)

DevTools (require BiDi — Firefox + geckodriver ≥ 0.34)

Tool

Description

devtools_report

Main diagnostic tool — JS errors + console + failed/slow network

devtools_js_errors

JavaScript exceptions only (entries carry an untrusted marker)

devtools_console

Console output (log / warn / error / info / debug; entries carry an untrusted marker)

devtools_network_failed

Failed resources (4xx, 5xx, DNS errors)

devtools_network_all

All network requests (supports limit= and filters)

devtools_clear

Clear buffered DevTools data (use before navigating)

devtools_enable_bidi

Attach BiDi listeners to a running session

devtools_computed_css

Computed CSS properties of an element

devtools_element_info

Bounding box, visibility, attributes, aria, outerHTML

devtools_css_variables

CSS custom properties (--var) in scope


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

Variable

Default

Description

GECKODRIVER_PATH

(unset)

Absolute path to geckodriver binary (highest priority)

GECKODRIVER_AUTO_INSTALL

true

Set to false to disable webdriver-manager fallback

FIREFOX_BINARY

(unset)

Path to a custom Firefox executable

FIREFOX_PROFILE

(unset)

Named Firefox profile — same as -P

FIREFOX_PROFILE_DIR

(unset)

Profile directory path — same as --profile

WEBDRIVER_READONLY

true

Set to false to allow page-mutating tools (click/fill/upload/select/execute_js/press_key/dialogs/cookies/storage). Empty/unset values stay read-only (fail-closed).


geckodriver resolution order

#

Source

Configure via

1

GECKODRIVER_PATH env variable

Absolute path to the binary

2

System PATH (default)

apt install gecko-driver from repo.vitexsoftware.com

3

webdriver-manager auto-download

Fallback; disable with GECKODRIVER_AUTO_INSTALL=false


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"

# Live capability scenario (opens about:blank when geckodriver+Firefox exist):
python tests/live_capability_scenario.py

# All tests including browser integration:
pytest tests/

The live scenario respects WEBDRIVER_READONLY=true (default): mutating tools must refuse, while session/read tools open about:blank, call browser_status / browser_get_title / browser_get_url / browser_get_source, then browser_close. If /usr/bin/geckodriver or Firefox is missing, browser steps are skipped gracefully (exit 0).


Server

Description

abraflexi-mcp-server

AbraFlexi accounting/ERP integration — invoices, contacts, products, bank transactions

mastodon-mcp-server

Mastodon integration — timelines, posting, account management, search

semaphore-mcp-server

Semaphore UI integration — manage Ansible, Terraform and other automation workflows


License

MIT

Available Tools

43 tools
browser_accept_dialogA

Accept (click OK on) a JavaScript dialog: alert(), confirm(), or prompt().

Call this when a browser action triggers a dialog that blocks further interaction.

Inputs: no named parameters. Returns: result

browser_backA

Navigate back.

Inputs: no named parameters. Returns: result

browser_clear_storageA

Remove one key or clear all entries from localStorage or sessionStorage.

Inputs: key, storage. Returns: result

browser_clickC

Click an element.

Inputs: selector (required). Returns: result

browser_closeA

Close the browser session. All buffered DevTools data is discarded.

Inputs: no named parameters. Returns: result

browser_dismiss_dialogA

Dismiss (click Cancel on) a JavaScript confirm() or prompt() dialog, or close an alert().

Inputs: no named parameters. Returns: result

browser_execute_jsA

Execute JavaScript and return the result as JSON (falls back to str for non-serialisable values).

Inputs: script (required). Returns: result

browser_fillC

Type text into an input field.

Inputs: value (required), selector (required), clear_first. Returns: result

browser_find_elementsA
Read-only

Return a list of all elements matching a CSS selector.

Each entry contains: index, tag, text (first 200 chars), id, class, href, src, value, type, name, visible, and aria-label.

Useful for enumerating links, buttons, inputs, or any repeated component.

Inputs: selector (required), limit. Returns: result

browser_forwardB

Navigate forward.

Inputs: no named parameters. Returns: result

browser_get_attributeA
Read-only

Return the value of an HTML attribute on an element.

Inputs: selector (required), attribute (required). Returns: result

browser_get_cookiesA
Read-only

Return all cookies for the current page as a list of dicts.

Each entry: name, value, domain, path, secure, httpOnly, expiry. Useful for inspecting authentication state or session tokens.

Inputs: no named parameters. Returns: result

browser_get_sourceA
Read-only

Return the full HTML source of the current page.

Inputs: no named parameters. Returns: result

browser_get_storageA
Read-only

Read from localStorage or sessionStorage.

Returns all key→value pairs when no key is given, or {key: value} for a single key (value is null if the key does not exist).

Useful for inspecting auth tokens, cached API responses, feature flags, or any client-side state stored in web storage rather than cookies.

Inputs: key, storage. Returns: object

browser_get_textA
Read-only

Get visible text content of the page or a specific element.

Inputs: selector. Returns: result

browser_get_titleA
Read-only

Return the of the current page.

Inputs: no named parameters. Returns: result

browser_get_urlA
Read-only

Return the current URL.

Inputs: no named parameters. Returns: result

browser_hoverA
Read-only

Move the mouse over an element (hover).

Triggers CSS :hover states and any mouseenter/mouseover event listeners — essential for dropdown menus, tooltips, and hover-activated controls.

Inputs: selector (required). Returns: result

browser_navigateA

Navigate to a URL in the existing session (keeps BiDi listeners active).

Inputs: url (required). Returns: result

browser_openA

Open URL in Firefox. Starts a new browser session if none is running.

With enable_bidi=True (default) the session automatically captures: • All JavaScript exceptions (file, line, column, stack trace) • All console.* output (log / warn / error / info / debug) • All network requests with status codes and durations

To test responsive / mobile layouts pass width + height (and optionally user_agent): width=390 height=844 — iPhone 14 width=375 height=667 — iPhone SE width=360 height=800 — Samsung Galaxy S21 width=768 height=1024 — iPad width=1280 height=800 — laptop

geckodriver sources (priority order):

  1. GECKODRIVER_PATH env → 2. apt install gecko-driver → 3. webdriver-manager

Inputs: url, width, height, headless, +4 more. Returns: result

browser_press_keyA

Send a keyboard key press to an element or the currently focused element.

Useful for submitting forms (enter), moving focus (tab), closing modals (escape), or triggering keyboard-driven UI components.

Inputs: key (required), selector. Returns: result

browser_refreshA

Reload the current page.

Inputs: no named parameters. Returns: result

browser_screenshotA
Read-only

Take a PNG screenshot for visual / layout / CSS diagnosis.

Capture the full page to spot broken layout, or pass a CSS selector to isolate a specific component (header, nav, modal…). The agent can use this to identify misaligned elements, invisible text, broken flex/grid layouts, or unstyled components.

Inputs: selector.

browser_scrollA

Scroll the page or scroll an element into view.

• Pass a CSS selector to scroll that element into view (smoothly). • Pass x/y to jump the page to absolute scroll coordinates. • Pass by=true with x/y to scroll relative to the current position (e.g. y=500 scrolls down 500 px). • No arguments scrolls to the top of the page.

Inputs: x, y, by, selector. Returns: result

browser_selectA

Select an in a dropdown.

Inputs: value (required), selector (required). Returns: result

browser_set_storageA

Write a key→value pair to localStorage or sessionStorage.

Useful for injecting auth tokens, feature flags, or test fixtures directly into web storage without going through a login or setup flow.

Inputs: key (required), value (required), storage. Returns: result

browser_set_viewportA

Resize the browser viewport to test responsive / mobile layouts.

Call this at any point during a session to switch between breakpoints.

Common presets: 390×844 — iPhone 14 375×667 — iPhone SE 360×800 — Samsung Galaxy S21 768×1024 — iPad 1280×800 — laptop 1920×1080 — desktop full-HD

Inputs: width (required), height (required). Returns: result

browser_statusA
Read-onlyIdempotent

Session state, geckodriver info, BiDi status and buffer sizes.

Inputs: no named parameters. Returns: object

browser_switch_frameB

Switch into an or back to the main document.

Inputs: selector. Returns: result

browser_upload_fileA

Upload a local file through a element.

Works even when the file input is visually hidden (the common pattern of hiding the native input and styling a custom button over it). The file must exist on the machine running the MCP server.

Inputs: path (required), selector (required). Returns: result

browser_waitA
Read-only

Wait until an element satisfies a condition: visible, clickable, present in DOM, or contains text.

Inputs: selector (required), timeout, condition. Returns: result

devtools_clearA

Clear all buffered console, JS error, and network entries.

Call this before navigating to a new page to get a clean baseline, so subsequent devtools_* calls only reflect the new page's activity.

Inputs: no named parameters. Returns: result

devtools_computed_cssA
Read-only

Return computed (final applied) CSS properties of an element.

Use this to understand why an element looks wrong: • Is it display:none or visibility:hidden? • What color / font is actually applied? • Is a CSS variable resolving correctly? • Are grid/flex dimensions what you expect?

Returns a dict of {property: computed_value}.

Inputs: selector (required), properties. Returns: object

devtools_consoleA
Read-only

Return buffered browser console messages.

Each entry: ts, level, text, url (source file), line. Covers console.log / warn / error / info / debug.

Inputs: level, since. Returns: result

devtools_css_variablesA
Read-only

Return CSS custom properties (variables) defined on :root.

Helps diagnose theming issues: missing tokens, wrong colour values, variables that weren't loaded because a CSS file failed to fetch.

Inputs: prefix. Returns: object

devtools_element_infoA
Read-only

Return detailed info about a DOM element for debugging:

• outerHTML — the element's markup (first 4000 chars) • bounding_box — position and size on screen (x, y, width, height) • visible — whether the element is actually visible • in_viewport — whether it's within the visible scroll area • attributes — all HTML attributes • aria — ARIA role, name, label, disabled, hidden • child_count — number of child elements • text_content — visible text (first 500 chars)

Use this to diagnose elements that should be visible but aren't, or to understand the structure around a broken component.

Inputs: selector (required). Returns: object

devtools_enable_bidiA

Attach (or re-attach) WebDriver BiDi listeners to the running session.

Use if the session was opened with enable_bidi=False, or if listeners were lost after a page crash.

Inputs: no named parameters. Returns: result

devtools_js_errorsA
Read-only

Return all JavaScript exceptions captured since browser_open.

Each entry contains: ts — ISO 8601 timestamp type — error type (e.g. 'TypeError', 'ReferenceError') text — error message url — source file URL line — line number in source file column — column number stack — full stack trace

This is the primary tool for finding which JS file and line causes a bug.

Inputs: since. Returns: result

devtools_network_allA
Read-only

Return all captured network requests with filtering options.

Useful for auditing which CSS/JS files are loaded, checking API response times, or finding resources that are unexpectedly missing from the page. Use limit= to avoid overwhelming the context window on busy pages.

Inputs: limit, since, slow_ms, min_status, +1 more. Returns: result

devtools_network_failedA
Read-only

Return network requests that FAILED — 4xx / 5xx status or DNS / connection errors.

This is how the agent detects broken CSS files, missing JS bundles, unavailable fonts, or failed API calls that cause layout or functionality issues.

Each entry: ts, method, url, type, status (0 = connection failed), duration_ms, failed (bool), error (error description).

Inputs: since, resource_type. Returns: result

devtools_performanceA
Read-only

Return page performance timing from the browser Navigation Timing API.

navigation — key milestones for the current page load: ttfb_ms — Time to First Byte (server latency) dom_loaded_ms — DOMContentLoaded (page parsed, defer scripts done) load_ms — full load event (all resources fetched) dns_ms — DNS lookup duration connect_ms — TCP/TLS connection duration request_ms — time from request sent to last response byte transfer_size — response body size in bytes

resources (when include_resources=True) — per-asset breakdown: name, type, duration_ms, transfer_size, start_time

Use this to identify slow pages, expensive assets, or server latency. Complements devtools_network_all which captures requests via BiDi listeners.

Inputs: include_resources. Returns: object

devtools_reportA
Read-only

MAIN DIAGNOSTIC TOOL — returns a complete DevTools report in one call:

• js_errors — all JavaScript exceptions with file, line, column, stack • console_errors — console.error() and console.warn() output • failed_resources — CSS / JS / images / fonts that returned 4xx/5xx or failed to load • slow_resources — requests that took longer than 2 s

Use this after navigating to a page or after triggering a UI action. Equivalent to opening DevTools and checking the Console + Network tabs.

Inputs: since. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 43 tools

    Disambiguation4/5

    Most tools target a distinct resource or action, and the browser_* vs devtools_* prefixes make intent clear. The main overlap is devtools_report, which aggregates what devtools_js_errors, devtools_console, and devtools_network_failed already expose, but their overview-vs-focused relationship is explained well enough.

    Naming Consistency4/5

    Names are snake_case and follow a readable prefix pattern: browser_<verb-like action> and devtools_<inspection/data>. Minor deviations like browser_status, browser_screenshot, and the noun-style devtools_* names keep it from being fully verb_noun, but the convention is predictable.

    Tool Count2/5

    43 tools is above the 25+ threshold and creates a heavy selection surface for an agent, even though the webdriver domain is broad. Some devtools_* getters could be consolidated, and the set would benefit from tighter scoping or splitting browser and devtools concerns.

    Completeness4/5

    The surface covers navigation, interaction, waiting, frames, dialogs, cookies/storage, screenshots, and detailed devtools diagnostics. Notable gaps like multi-tab/window management and drag-and-drop are missing, but most core webdriver workflows are fully supported.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers