Metadata-Version: 2.4
Name: mcp-server-webdriver
Version: 0.6.0
Summary: MCP Server for browser automation via Selenium WebDriver + geckodriver (Firefox)
License: MIT
License-File: LICENSE
Keywords: browser-automation,firefox,geckodriver,mcp,selenium,webdriver
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.10.0
Requires-Dist: selenium>=4.0.0
Provides-Extra: auto-driver
Requires-Dist: webdriver-manager>=4.0.0; extra == 'auto-driver'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: webdriver-manager>=4.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# mcp-server-webdriver

![mcp-server-webdriver](mcp-server-webdriver.svg)

MCP Server that lets AI agents control a real web browser via **Selenium WebDriver** (Firefox + geckodriver).  
Built with [FastMCP](https://gofastmcp.com).

---

## 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

| Dependency | Version |
|---|---|
| Python | ≥ 3.11 |
| [FastMCP](https://pypi.org/project/fastmcp/) | ≥ 2.10 |
| [selenium](https://pypi.org/project/selenium/) | ≥ 4.0 |
| Firefox | any recent |
| [geckodriver](https://github.com/mozilla/geckodriver) | ≥ 0.34 |

---

## Installation

### Recommended — Debian package from VitexSoftware repository

```bash
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" \
  | sudo tee /etc/apt/sources.list.d/vitexsoftware.list
sudo apt update
sudo apt install python3-mcp-server-webdriver
```

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

### Alternative — system package manager

```bash
# 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:

```bash
pip install fastmcp selenium
```

### Fallback — webdriver-manager (auto-download)

```bash
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:

```json
{
  "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.

---

### 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 |
| `browser_get_text` | Visible text (whole page or CSS selector) |
| `browser_get_attribute` | Value of an HTML attribute on an element |
| `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 |
| `devtools_console` | Console output (log / warn / error / info / debug) |
| `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 |

---

## 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` |

---

## 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:

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

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

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

With a profile directory and explicit geckodriver path:

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

---

## Running tests

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

# All tests including browser integration:
pytest tests/
```

---

## Related MCP Servers by VitexSoftware

| Server | Description |
|---|---|
| [abraflexi-mcp-server](https://github.com/VitexSoftware/abraflexi-mcp-server) | AbraFlexi accounting/ERP integration — invoices, contacts, products, bank transactions |
| [mastodon-mcp-server](https://github.com/VitexSoftware/mastodon-mcp-server) | Mastodon integration — timelines, posting, account management, search |
| [semaphore-mcp-server](https://github.com/VitexSoftware/semaphore-mcp-server) | Semaphore UI integration — manage Ansible, Terraform and other automation workflows |

---

## License

MIT
