Skip to main content
Glama

mcp-selenium

A production-ready MCP (Model Context Protocol) server that exposes Selenium 4 browser automation as MCP tools. Supports Chrome and Firefox with full BiDi (Bidirectional API) event streaming.


Architecture

selenium-mcp/
├── server.py               # MCP entrypoint (JSON-RPC 2.0 over stdio)
├── config/
│   ├── settings.py         # ENV + YAML config loader (singleton)
│   ├── default.yaml        # Default configuration values
│   └── logging_config.py   # Structured logging setup
├── driver/
│   ├── factory.py          # WebDriver factory (Chrome / Firefox + BiDi)
│   ├── session.py          # BrowserSession – wraps a single WebDriver
│   └── session_manager.py  # Registry of all active sessions
├── events/
│   ├── dispatcher.py       # Async pub/sub event dispatcher (asyncio.Queue)
│   ├── bidi_listeners.py   # BiDi WebSocket event listeners
│   └── network_interceptor.py  # CDP/BiDi network interception
├── tools/
│   ├── base.py             # BaseTool + error-screenshot decorator
│   ├── navigation_tools.py # open_page, navigate_back/forward, get_dom
│   ├── interaction_tools.py# click, type_text, get_text, wait_for
│   ├── script_tools.py     # execute_js, screenshot
│   ├── log_tools.py        # get_console_logs, get_network_logs, intercept_requests
│   ├── session_tools.py    # create_session, close_session, list_sessions
│   └── registry.py         # Tool name → callable map + MCP descriptors
└── models/
    ├── session.py          # SessionInfo, BrowserType, SessionStatus
    ├── events.py           # BrowserEvent, ConsoleLogEvent, NetworkRequestEvent, …
    ├── network.py          # NetworkLog, ConsoleLog, InterceptRule, PerformanceMetrics
    └── exceptions.py       # Custom exception hierarchy

Layered design

MCP Client (Claude / any MCP host)
        ↕  JSON-RPC 2.0 / stdio
    server.py  (MCPServer)
        ↕
    tools/registry.py  →  tools/*.py  (business logic)
        ↕
    driver/session_manager.py  →  driver/session.py
        ↕                               ↕
    driver/factory.py           events/bidi_listeners.py
    (WebDriver creation)        (BiDi / CDP event capture)
        ↕                               ↕
    Selenium 4 WebDriver       events/dispatcher.py
    (Chrome / Firefox)         (async pub/sub)

Related MCP server: open_browser_use

Quick start

Prerequisites

Requirement

Version

Python

3.11+

Chrome / ChromeDriver

latest stable

Firefox / GeckoDriver

latest stable (optional)

Installation

# 1. Clone / enter the project
git clone <repo> selenium-mcp
cd selenium-mcp

# 2. Create a virtual environment
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. (Optional) install as editable package
pip install -e .

Run the server

# Stdio mode (standard MCP transport)
python server.py

# Or via the installed entry-point
selenium-mcp

The server reads JSON-RPC 2.0 messages from stdin and writes responses to stdout.


Configuration

Configuration is loaded in priority order:

  1. Environment variables (SMCP_*)

  2. YAML file (SMCP_CONFIG_FILE env var or config/default.yaml)

  3. Built-in defaults

Key settings

ENV variable

YAML key

Default

Description

SMCP_BROWSER

browser.default

chrome

Default browser (chrome/firefox)

SMCP_HEADLESS

browser.headless

true

Run headless

SMCP_MAX_SESSIONS

browser.max_sessions

5

Max concurrent sessions

SMCP_BIDI_ENABLED

bidi.enabled

true

Enable BiDi WebSocket

SMCP_LOG_LEVEL

server.log_level

INFO

Log level

SMCP_DEBUG

server.debug

false

Verbose debug logging

SMCP_SCREENSHOT_ON_ERROR

screenshot.on_error

true

Auto-screenshot on errors

SMCP_SCREENSHOT_DIR

screenshot.directory

screenshots/

Screenshot output dir

Custom YAML config

SMCP_CONFIG_FILE=/path/to/my-config.yaml python server.py

Example my-config.yaml:

browser:
  default: firefox
  headless: false
  max_sessions: 3
bidi:
  enabled: true
screenshot:
  on_error: true
  directory: /tmp/mcp-screenshots

MCP Tools reference

Session management

Tool

Description

Key params

create_session

Open a new browser

browser, headless

close_session

Close a session

session_id

list_sessions

List active sessions

—

get_session_info

Get session metadata

session_id

Navigation

Tool

Description

Key params

open_page

Navigate to URL

url

navigate_back

History back

—

navigate_forward

History forward

—

get_dom

Full page HTML

—

Element interaction

Tool

Description

Key params

click

Click a CSS selector

selector

type_text

Type into an input

selector, text

get_text

Get element text

selector

wait_for

Wait until visible

selector, timeout

wait_for_dom_stable

Smart DOM-stability wait

timeout

Script & media

Tool

Description

Key params

execute_js

Run JavaScript

script

screenshot

Capture viewport (base64 PNG)

—

Logs & network

Tool

Description

Key params

get_console_logs

Browser console entries

—

get_network_logs

Network request/response log

—

get_performance_metrics

Page timing data

—

intercept_requests

Register URL intercept rule

pattern, action


Connecting to MCP clients

uvx mcp_selenium

Via pip

pip install mcp_selenium
selenium-mcp

Local development (uv run)

git clone https://github.com/SCV-Consultants/selenium-mcp.git
cd selenium-mcp
uv run selenium-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "selenium": {
      "command": "uvx",
      "args": ["mcp_selenium"],
      "env": {
        "SMCP_HEADLESS": "false",
        "SMCP_BROWSER": "chrome"
      }
    }
  }
}

Antigravity / Gemini

Add to your MCP config (mcp_config.json):

{
  "mcpServers": {
    "selenium": {
      "command": "uvx",
      "args": ["mcp_selenium"],
      "env": {
        "SMCP_HEADLESS": "false",
        "SMCP_BROWSER": "chrome"
      }
    }
  }
}

For local development, use uv run instead:

{
  "mcpServers": {
    "selenium": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/selenium-mcp", "selenium-mcp"],
      "env": {
        "SMCP_HEADLESS": "false",
        "SMCP_BROWSER": "chrome"
      }
    }
  }
}

Claude CLI

claude mcp add selenium -- uvx mcp_selenium

Install via Smithery

npx -y @smithery/cli install mcp_selenium --client claude

BiDi / Event system

When bidi.enabled: true the server attaches BiDi WebSocket listeners to each session:

  • Console events – console.log, console.error, etc. are captured and stored per-session. Retrieved via get_console_logs.

  • JS errors – JavaScript runtime errors are captured as error-level console entries.

  • Network events – CDP Network.enable (Chrome) captures request/response data. Retrieved via get_network_logs.

  • Event dispatcher – All events flow through an asyncio.Queue-backed pub/sub hub (events/dispatcher.py). Custom async handlers can be registered per event type for real-time streaming use cases.


Error handling

All tools wrap failures in a typed exception hierarchy:

Exception

Trigger

SessionNotFoundError

Invalid session_id

SessionLimitError

Too many concurrent sessions

ElementNotFoundError

CSS selector matched nothing

ElementInteractionError

Element not clickable/typeable

NavigationError

get() / history navigation failed

ScriptExecutionError

JavaScript threw or timed out

TimeoutError

wait_for condition not met

NetworkInterceptionError

CDP interception setup failed

BiDiNotSupportedError

BiDi requested but unavailable

When screenshot.on_error: true, a PNG is saved to screenshot.directory automatically on any SeleniumMCPError.


Development

# Lint
ruff check .

# Type check
mypy .

# Tests
pytest tests/ -v

Retry mechanism

All element interactions use an internal _retry() helper that retries on StaleElementReferenceException and transient WebDriverException. Configurable via:

retry:
  max_attempts: 3
  backoff_seconds: 1.0

Available Tools

27 tools
alertB

Handle browser alert/confirm/prompt dialogs. Actions: accept, dismiss, get_text, send_text.

Inputs: action (required), text, session_id. Returns: result

clickB

Click a DOM element by CSS selector.

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

close_sessionC

Close a browser session by ID.

Inputs: session_id (required). Returns: result

create_sessionC

Create a new browser session. Defaults to Chrome headless.

Inputs: browser, headless. Returns: result

execute_jsC

Execute JavaScript in the browser and return the result.

Inputs: script (required), session_id. Returns: result

frameC

Switch focus to a frame or back to the main page. Actions: switch, default.

Inputs: action (required), identifier, session_id. Returns: result

get_attributeB

Get an attribute value from a DOM element (e.g. href, value, class).

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

get_console_logsB

Return all captured browser console log entries.

Inputs: session_id. Returns: result

get_cookiesC

Get cookies. Returns all or a specific one by name.

Inputs: name, session_id. Returns: result

get_domC

Return the full page HTML source.

Inputs: session_id. Returns: result

get_network_logsC

Return all captured network request/response entries.

Inputs: session_id. Returns: result

get_performance_metricsC

Return page performance timing data.

Inputs: session_id. Returns: result

get_session_infoC

Get metadata for a browser session.

Inputs: session_id. Returns: result

get_textB

Get the visible inner text of an element.

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

intercept_requestsC

Register a URL pattern for network interception (log or block).

Inputs: pattern (required), action, session_id. Returns: result

list_sessionsA

List all active browser sessions.

Inputs: no named parameters. Returns: result

open_pageC

Navigate the browser to a URL.

Inputs: url (required), session_id. Returns: result

press_keyB

Press a keyboard key (e.g. Enter, Tab, Escape). Optionally target a specific element.

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

screenshotC

Capture a base64-encoded PNG screenshot of the current viewport.

Inputs: session_id. Returns: result

type_textB

Clear an input and type text into it.

Inputs: selector (required), text (required), session_id. Returns: result

wait_forB

Wait until a CSS selector is visible on the page.

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

wait_for_dom_stableC

Wait until the DOM stops mutating (smart wait for AJAX content).

Inputs: timeout, session_id. Returns: result

windowC

Manage browser windows and tabs. Actions: list, switch, switch_latest, close.

Inputs: action (required), handle, index, session_id. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 27 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose, from navigation (open_page, navigate_back) to element interaction (click, type_text, press_key) to session management. Even similar tools like wait_for and wait_for_dom_stable are differentiated by descriptions.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., add_cookie, get_text, wait_for_dom_stable). Even single-word names like 'alert' and 'click' align with the pattern as short verbs.

    Tool Count4/5

    27 tools is on the higher side but reasonable for a comprehensive browser automation server. The number covers essential operations across sessions, navigation, elements, cookies, and debugging, without feeling bloated.

    Completeness4/5

    The tool surface covers all core browser automation tasks: navigation, element interaction, JavaScript execution, cookies, frames, windows, alerts, performance/network/console logs, and waiting. Minor gaps exist (e.g., file uploads, drag-and-drop) but these are advanced features not critical for most workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Exposes Selenium WebDriver as an MCP server, enabling AI agents and LLMs to control real browsers for automation tasks like navigation, element interaction, and screenshot capture.
      22
      3
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server for web automation using Selenium WebDriver, enabling AI assistants to navigate, interact with elements, take screenshots, and manage browser storage.
      15 PyPI
      10
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Selenium-based MCP server that exposes browser automation tools for navigation, interaction, form filling, and assertions, enabling AI agents to control web browsers through natural language.
      1
      GPL 3.0