selenium-mcp
Provides tools for browser automation using Selenium WebDriver, enabling AI agents to control Chrome and Firefox browsers for tasks like navigation, element interaction, screenshot capture, and network log retrieval.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@selenium-mcp open google.com and search for MCP servers"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 hierarchyLayered 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-mcpThe server reads JSON-RPC 2.0 messages from stdin and writes responses to stdout.
Configuration
Configuration is loaded in priority order:
Environment variables (
SMCP_*)YAML file (
SMCP_CONFIG_FILEenv var orconfig/default.yaml)Built-in defaults
Key settings
ENV variable | YAML key | Default | Description |
|
|
| Default browser ( |
|
|
| Run headless |
|
|
| Max concurrent sessions |
|
|
| Enable BiDi WebSocket |
|
|
| Log level |
|
|
| Verbose debug logging |
|
|
| Auto-screenshot on errors |
|
|
| Screenshot output dir |
Custom YAML config
SMCP_CONFIG_FILE=/path/to/my-config.yaml python server.pyExample my-config.yaml:
browser:
default: firefox
headless: false
max_sessions: 3
bidi:
enabled: true
screenshot:
on_error: true
directory: /tmp/mcp-screenshotsMCP Tools reference
Session management
Tool | Description | Key params |
| Open a new browser |
|
| Close a session |
|
| List active sessions | — |
| Get session metadata |
|
Navigation
Tool | Description | Key params |
| Navigate to URL |
|
| History back | — |
| History forward | — |
| Full page HTML | — |
Element interaction
Tool | Description | Key params |
| Click a CSS selector |
|
| Type into an input |
|
| Get element text |
|
| Wait until visible |
|
| Smart DOM-stability wait |
|
Script & media
Tool | Description | Key params |
| Run JavaScript |
|
| Capture viewport (base64 PNG) | — |
Logs & network
Tool | Description | Key params |
| Browser console entries | — |
| Network request/response log | — |
| Page timing data | — |
| Register URL intercept rule |
|
Connecting to MCP clients
Via uvx (recommended — zero install)
uvx mcp_seleniumVia pip
pip install mcp_selenium
selenium-mcpLocal development (uv run)
git clone https://github.com/SCV-Consultants/selenium-mcp.git
cd selenium-mcp
uv run selenium-mcpClaude 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_seleniumInstall via Smithery
npx -y @smithery/cli install mcp_selenium --client claudeBiDi / 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 viaget_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 viaget_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 |
| Invalid |
| Too many concurrent sessions |
| CSS selector matched nothing |
| Element not clickable/typeable |
|
|
| JavaScript threw or timed out |
|
|
| CDP interception setup failed |
| 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/ -vRetry 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.0Available Tools
27 toolsadd_cookieC
Add a cookie. Browser must be on a page from the cookie's domain.
Inputs: name (required), value (required), domain, path, +3 more. Returns: result
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
delete_cookieC
Delete cookies. Deletes all or a specific one by name.
Inputs: name, session_id. 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
Scored across 27 tools
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.
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.
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.
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
Related MCP Connectors
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
MCP server to assist with JxBrowser development.
Unofficial Browserless MCP — wraps the Browserless headless-Chromium REST API (browserless.io)
MCP server for Mint — AI-powered QA that runs your app in a real browser on every PR.
Related MCP Servers
- AlicenseAqualityDmaintenanceExposes 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.223MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for browser automation, exposing tools for tab management, navigation, CDP, action plans, and cleanup.428MIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server for web automation using Selenium WebDriver, enabling AI assistants to navigate, interact with elements, take screenshots, and manage browser storage.15 PyPI10MIT
- AlicenseNot gradedqualityDmaintenanceA 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.1GPL 3.0