Selenium MCP Server

What PhungXuanAnh/selenium-mcp-server does

PhungXuanAnh/selenium-mcp-server brings Chrome browser control to MCP clients through Selenium WebDriver. It can open URLs, check page readiness, manage multiple tabs, locate elements, click controls, fill inputs, and capture screenshots. Element queries can use text, class names, IDs, attributes, element types, XPath, or iframe identifiers.

The server also exposes browser-level and page-level inspection capabilities. Agents can retrieve an element's CSS or computed styles, run JavaScript, read console output, inspect network events, and retrieve a response body by request ID. Browser local storage supports adding, reading, updating, and removing values. Video recording can target a fixed tab or follow active-tab switches among selected tabs.

How it works

The MCP process uses Selenium WebDriver to control Chrome. It can connect to an existing Chrome instance or start a new one. Browser operations apply to the active tab unless a tool accepts a window handle or explicitly selects another tab.

Tab handles returned by list_tabs can be passed to switch_tab or close_tab. Element tools accept several selector fields and can target content inside an iframe by ID or name. The server supports a default compact tool profile and an explicit --tool-profile legacy compatibility profile. The legacy profile exposes 24 tools across navigation, element interaction, styling, JavaScript, logging, and local storage.

Screenshot paths use a workspace-oriented default location or an explicitly supplied directory. Video recording supports MP4 output and can add a synthetic URL header; recording should be stopped immediately after the final browser action.

Setup and configuration

The recommended installation uses the Python package:

pip install mcp-server-selenium
python -m mcp_server_selenium --port 9222 --user_data_dir /tmp/chrome-debug

For source-based development, clone the repository, install dependencies with uv sync, and run the module with the source directory on PYTHONPATH:

git clone https://github.com/PhungXuanAnh/selenium-mcp-server.git
cd selenium-mcp-server
uv sync
PYTHONPATH=src python -m mcp_server_selenium --port 9222 --user_data_dir /tmp/chrome-debug

Chrome setup is part of the installation process because Selenium drives the browser. The command-line options shown here configure the listening port and Chrome user-data directory. The project also documents MCP Inspector usage for testing and configuration with MCP clients.

Tools and capabilities

The documented tool surface includes:

• Navigate to pages, wait for readiness, list tabs, open tabs, switch tabs, and close tabs.
• Find one or many elements, paginate element results, inspect direct children, click elements, and set input values.
• Retrieve regular or computed styles, with optional HTML output.
• Execute JavaScript alone or return its value together with newly captured console output.
• Consume console logs with level filtering and network logs with URL or error filtering.
• Retrieve a network response body using its request ID.
• Add, read, update, and remove individual or all local-storage entries.
• Capture named PNG screenshots and record browser-tab video.

Limitations and notes

The server is designed around Chrome and Selenium WebDriver, so browser setup is required before automation can run. Element operations depend on selectors or identifying fields such as text, IDs, attributes, element types, XPath, or iframe identifiers. Network and console log reads consume the available log entries, and network response retrieval requires a request ID obtained from network logging. The legacy profile is intended as a compatibility fallback; the compact profile is the default.