SeleniumMCP

Deployment-ready Python MCP server for Selenium browser automation. It supports local STDIO usage and production-style Streamable HTTP at /mcp, plus health endpoints for container platforms.

Tools

• browser_start, browser_stop, browser_reset, browser_state
• navigate, go_back, go_forward, refresh
• set_window_size, open_new_tab, switch_window, close_window
• find_element, wait_for_element, click, type_text
• get_text, get_attribute, execute_script, scroll
• page_source, screenshot, save_screenshot
• list_cookies, add_cookie, delete_cookies

Locator strategies: id, name, css selector, xpath, link text, partial link text, tag name, class name.

HTTP Endpoints

• POST /mcp and related Streamable HTTP MCP calls
• GET /healthz
• GET /readyz
• POST /browser/start
• POST /browser/stop

Local Setup

Windows Python Prerequisite

If PowerShell says Python was not found, install Python 3.11+ first. The quickest options are:

winget install Python.Python.3.12

Then close and reopen PowerShell. If python --version still opens the Microsoft Store prompt, disable the python.exe and python3.exe app execution aliases in:

Settings > Apps > Advanced app settings > App execution aliases

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

Run as a local STDIO MCP server:

selenium-mcp

Run as a Streamable HTTP MCP server:

selenium-mcp-http

Then connect MCP clients to:

http://localhost:8000/mcp

Claude Desktop Example

{
  "mcpServers": {
    "selenium": {
      "command": "selenium-mcp",
      "env": {
        "SELENIUM_BROWSER": "chrome",
        "SELENIUM_HEADLESS": "true"
      }
    }
  }
}

Docker

Build and run with an in-container Chromium browser:

docker build -t selenium-mcp .
docker run --rm -p 8000:8000 selenium-mcp

Run with a dedicated Selenium Grid browser container:

docker compose up --build

Configuration

Copy .env.example to .env and adjust:

SELENIUM_BROWSER=chrome
SELENIUM_HEADLESS=true
SELENIUM_REMOTE_URL=
SELENIUM_IMPLICIT_WAIT_SECONDS=2
SELENIUM_PAGE_LOAD_TIMEOUT_SECONDS=30
SELENIUM_SCRIPT_TIMEOUT_SECONDS=30
SELENIUM_WINDOW_WIDTH=1440
SELENIUM_WINDOW_HEIGHT=1000
SELENIUM_ALLOW_FILE_URLS=false
SELENIUM_DEFAULT_DOWNLOAD_DIR=/tmp/selenium-downloads
SELENIUM_HTTP_HOST=0.0.0.0
SELENIUM_HTTP_PORT=8000
SELENIUM_MCP_TRANSPORT=stdio

For remote Selenium Grid, set:

SELENIUM_REMOTE_URL=http://selenium:4444/wd/hub

Security Notes

This server can browse the web, execute JavaScript, read page HTML, and save screenshots on the host. In production, run it in a locked-down container or VM, restrict outbound network access, keep SELENIUM_ALLOW_FILE_URLS=false, and put the HTTP MCP endpoint behind your platform authentication layer.

Validation

ruff check .
pytest