🎭 Selenium MCP Server

Model Context Protocol server for browser automation using Selenium WebDriver.

66 tools for navigation, interaction, screenshots, assertions, cookies, tabs, HTTP API, recording, batch execution, iframes, and raw WebDriver access — all with strict hexagonal architecture.

Why this MCP?

Most Selenium MCPs expose basic WebDriver commands. This one adds the layers that make AI agents truly reliable:

| Feature | Status | | --------------------------------------------------------------------- | ------ | | Page snapshot with stable element refs (capture_page → e1, e2, ...) | ✅ | | Persistent per-domain selector hints | ✅ | | HTTP API tools (GET/POST/PUT/PATCH/DELETE) | ✅ | | Batch multi-step execution (up to 20 steps in 1 call) | ✅ | | Built-in test assertions | ✅ | | Raw WebDriver API access (run_selenium) | ✅ | | Recording for test generation | ✅ | | Dialog handling (alert/confirm/prompt) | ✅ | | Cookie management | ✅ | | Stealth mode | ✅ | | Strict hexagonal architecture (Domain/Ports/Adapters) | ✅ | | Session tracing (NDJSON) | ✅ | | Selenium Manager auto-provisioning | ✅ |

Quick Start

One-click install

From npm

npm install -g mcp-selenium-webdriver

Or run directly:

npx mcp-selenium-webdriver

Prerequisites

• Node.js 18+
• Chrome, Firefox, or Edge installed
• Selenium Manager provisions the matching driver automatically — no manual setup needed.

# Verify everything is ready
npx mcp-selenium-webdriver doctor

MCP Client Configuration

VS Code Copilot (.vscode/mcp.json):

{
  "servers": {
    "selenium-mcp": {
      "command": "npx",
      "args": ["mcp-selenium-webdriver"],
      "type": "stdio"
    }
  }
}

Claude Desktop:

{
  "mcpServers": {
    "selenium-mcp": {
      "command": "npx",
      "args": ["mcp-selenium-webdriver"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "selenium-mcp": {
      "command": "npx",
      "args": ["mcp-selenium-webdriver"]
    }
  }
}

Environment Variables

| Variable | Default | Description | | --------------------------------- | -------- | ------------------------------------ | | SELENIUM_BROWSER | chrome | Browser: chrome, firefox, edge | | SELENIUM_HEADLESS | false | Run browser in headless mode | | SELENIUM_STEALTH | false | Hide automation indicators | | SELENIUM_GRID_URL | — | Selenium Grid hub URL | | SELENIUM_MCP_OUTPUT_MODE | stdout | Output: stdout or file | | SELENIUM_MCP_OUTPUT_DIR | auto | Custom output directory | | SELENIUM_MCP_SAVE_TRACE | false | Save session trace as NDJSON | | SELENIUM_MCP_UNRESTRICTED_FILES | false | Bypass workspace sandbox | | HTTPS_PROXY / HTTP_PROXY | — | Corporate proxy |

Pass them in your MCP config:

{
  "mcpServers": {
    "selenium-mcp": {
      "command": "npx",
      "args": ["mcp-selenium-webdriver"],
      "env": {
        "SELENIUM_HEADLESS": "true",
        "SELENIUM_STEALTH": "true"
      }
    }
  }
}

CLI Flags

npx mcp-selenium-webdriver [flags]
npx mcp-selenium-webdriver doctor   # preflight diagnostics

| Flag | Description | | ---------------------------------- | ------------------------------------------------------- | | doctor | Run diagnostics (Chrome, driver, proxy, cache) and exit | | --headless | Run browser headless | | --stealth | Enable stealth mode | | --save-trace | Save session trace JSON | | --output-mode=stdout\|file | Set output mode | | --output-dir=<path> | Custom output directory | | --grid-url=<url> | Selenium Grid hub URL | | --allow-unrestricted-file-access | Bypass workspace sandbox |

Tools (66)

🧭 Navigation (7)

| Tool | Description | | ----------------- | ------------------------------------------------ | | navigate_to | Navigate to a URL. Starts browser automatically. | | go_back | Navigate back in history. | | go_forward | Navigate forward in history. | | refresh_page | Refresh the current page. | | scroll_page | Scroll the page or element into view. | | get_current_url | Get the current URL. Read-only. | | get_title | Get the page title. Read-only. |

📸 Page Analysis (5)

| Tool | Description | | ------------------ | ------------------------------------------------------------------------- | | capture_page | Capture page state as element list with stable refs (e1-e300). Read-only. | | get_page_source | Get the full HTML DOM. Read-only. | | get_visible_text | Get visible text, optionally scoped to a CSS selector. Read-only. | | get_visible_html | Get visible HTML (scripts removed by default). Read-only. | | take_screenshot | Take a screenshot (viewport, full-page, or element). |

🖱️ Elements (9)

| Tool | Description | | ---------------- | -------------------------------------------------- | | click_element | Click an element by CSS selector or ref. | | hover_element | Hover over an element. | | double_click | Double-click an element. | | right_click | Right-click (context menu) an element. | | select_option | Select a dropdown option by value, text, or index. | | drag_drop | Drag one element to another. | | teach_selector | Teach a preferred CSS selector for a domain. | | iframe_click | Click an element inside an iframe. | | iframe_fill | Fill an input inside an iframe. |

⌨️ Input (3)

| Tool | Description | | ------------- | ------------------------------------------------------------------------- | | input_text | Type text into an input field. | | key_press | Press a keyboard key, optionally with modifiers (ctrl, alt, shift, meta). | | file_upload | Upload a file through a file input. |

🖲️ Mouse (3)

| Tool | Description | | ------------- | ------------------------------------------- | | mouse_move | Move mouse to coordinates. | | mouse_click | Click at coordinates (left, right, middle). | | mouse_drag | Drag from one position to another. |

📑 Tabs (4)

| Tool | Description | | ------------ | ------------------------------ | | tab_list | List all open tabs. Read-only. | | tab_select | Switch to a specific tab. | | tab_new | Open a new tab. | | tab_close | Close a tab. |

✅ Verification (4)

| Tool | Description | | ------------------------ | -------------------------------------------------- | | verify_element_visible | Verify an element is visible. Read-only. | | verify_text_visible | Verify text is visible. Read-only. | | verify_value | Verify an input has the expected value. Read-only. | | verify_list_visible | Verify multiple texts are visible. Read-only. |

🌐 Browser Control (7)

| Tool | Description | | -------------------- | ------------------------------------------------------ | | wait_for | Wait for a condition (element visible, URL, title...). | | execute_javascript | Run JavaScript in the browser context. | | resize_window | Resize the browser window. | | dialog_handle | Handle dialogs (alert, confirm, prompt). | | console_logs | Get browser console logs with filtering. Read-only. | | network_monitor | Monitor network requests / toggle offline mode. | | pdf_generate | Generate a PDF from the current page. Read-only. |

🔄 Browser Lifecycle (5)

| Tool | Description | | ------------------ | -------------------------------------------------- | | start_browser | Start the browser explicitly with options. | | close_browser | Close the browser and end the session. | | reset_session | Reset the session (close + restart). | | set_stealth_mode | Enable/disable stealth mode. | | browser_status | Get session status (URL, title, state). Read-only. |

🍪 Cookies (3)

| Tool | Description | | --------------- | --------------------------- | | get_cookies | Get all cookies. Read-only. | | add_cookie | Add a cookie. | | delete_cookie | Delete a cookie by name. |

⏺️ Recording (4)

| Tool | Description | | ------------------ | -------------------------------------------- | | start_recording | Start recording actions for test generation. | | stop_recording | Stop recording and return the action log. | | recording_status | Check recording status. Read-only. | | clear_recording | Clear all recorded actions. |

💾 Selector Hints (4)

| Tool | Description | | ---------------------- | ------------------------------------------- | | selector_hint_save | Save a preferred CSS selector for a domain. | | selector_hint_get | Get saved hints for a domain. Read-only. | | selector_hint_list | List domains with hints. Read-only. | | selector_hint_delete | Delete a hint. |

🌍 HTTP API (5)

| Tool | Description | | ------------- | ---------------------------- | | http_get | HTTP GET request. Read-only. | | http_post | HTTP POST request with body. | | http_put | HTTP PUT request. | | http_patch | HTTP PATCH request. | | http_delete | HTTP DELETE request. |

⚡ Power Tools (3)

| Tool | Description | | -------------------------- | ----------------------------------------------------------------------------------- | | batch_execute | Execute up to 20 tool steps in a single call. | | run_selenium | Execute raw Selenium WebDriver API code (access to driver, By, until, Key). | | browser_generate_locator | Generate a robust locator for an element by description. Read-only. |

Architecture

Hexagonal architecture (Ports & Adapters):

src/
├── domain/
│   ├── models/          Pure types & value objects
│   ├── ports/           18 interfaces (IBrowserPort, INavigationPort...)
│   └── services/        16 use cases
├── adapters/
│   ├── selenium/        14 Selenium WebDriver implementations
│   ├── mcp/             MCP SDK server & tool registry
│   ├── persistence/     File system & selector hints storage
│   └── logging/         Console & trace (NDJSON) loggers
├── infrastructure/      DI container (tsyringe), bootstrap, config
├── index.ts             Entry point
└── cli.ts               CLI (doctor, flags)

Key design decisions:

• Dependency Injection via tsyringe with Symbol tokens — every port is swappable
• Zod would be used for runtime validation (planned)
• Selenium Manager auto-provisions chromedriver matching your installed Chrome version
• 16-phase selector engine for capture_page (ID → testId → role → label → ... → positional index)
• Stealth mode injects scripts to hide navigator.webdriver and automation indicators

Example Usage

Ask your AI agent:

Navigate to https://example.com, capture the page, click the first link, take a screenshot, verify "Example Domain" is visible.

The agent chains the tools automatically:

navigate_to → capture_page → click_element → take_screenshot → verify_text_visible

Or use raw WebDriver API:

run_selenium with:
  const el = await driver.findElement(By.css('h1'));
  const text = await el.getText();
  return text;

Batch execution:

batch_execute with:
  steps: [
    { tool: "navigate_to", args: { url: "https://example.com" } },
    { tool: "take_screenshot", args: { name: "before" } },
    { tool: "click_element", args: { selector: "a" } },
    { tool: "take_screenshot", args: { name: "after" } }
  ]

Development

git clone <this-repo>
cd mcp-selenium-webdriver
npm install
npm run build
npm run doctor

Scripts

npm run build          # Compile TypeScript
npm run dev            # Run with tsx (hot reload)
npm run typecheck      # Type-check without emitting
npm test               # Run all tests
npm run test:coverage  # Run tests with coverage

License

MIT