Selenium MCP Server

A Model Context Protocol (MCP) server that provides web automation capabilities through Selenium WebDriver. This server allows AI assistants to interact with web pages by providing tools for navigation, element interaction, taking screenshots, and more.

1.1. Quick Start

1.1.1. Using Installed Package (Recommended)

# Install
pip install mcp-server-selenium

# Run
python -m mcp_server_selenium --port 9222 --user_data_dir /tmp/chrome-debug

1.1.2. Using Source Code (Development)

# Clone and setup
git clone https://github.com/PhungXuanAnh/selenium-mcp-server.git
cd selenium-mcp-server
uv sync

# Run
PYTHONPATH=src python -m mcp_server_selenium --port 9222 --user_data_dir /tmp/chrome-debug

2. Features
3. Available Tools
4. Installation
5. Usage
6. Examples
- 6.1. Basic Web Automation
- 6.2. Advanced Usage
  - 6.2.1. JavaScript Examples
7. Logging
8. Troubleshooting
- 8.1. Common Issues
9. Architecture
10. Contributing
11. Support
12. Documentation
13. Reference

2. Features

Web Navigation: Navigate to URLs with timeout control and page readiness checking
Multiple Tabs: List, open, switch, and close browser tabs by window handle
Element Discovery & Interaction: Find elements by multiple criteria (text, class, ID, attributes, XPath) and interact with them through clicking and input value setting
Advanced Element Querying: Get single elements, multiple elements with pagination, and direct child nodes with comprehensive filtering options
Screenshots: Capture named PNG screenshots of the active tab in the default workspace location or an explicit output directory
Element Styling: Retrieve CSS styles and computed style information for any element
JavaScript Execution: Execute custom JavaScript code in browser console with optional console output capture
Browser Logging: Access console logs (with level filtering) and network request logs (with URL filtering and error filtering)
Local Storage Management: Complete CRUD operations for browser local storage (add, read, update, delete)
iFrame Support: Work with elements inside iframes using iframe ID or name targeting
XPath Support: Use XPath expressions for precise element targeting
Chrome Browser Control: Connect to existing Chrome instances or automatically start new ones

3. Available Tools

The default compact profile is documented in Compact Profile (Default). The explicit --tool-profile legacy compatibility fallback provides the following 23 tools with their original names and call contracts.

3.1. Navigation and Page Management

navigate(url, timeout) - Navigate to a specified URL with Chrome browser
check_page_ready(wait_seconds) - Check if the current page is fully loaded with optional wait
list_tabs() - List all browser tabs and identify the active tab
open_tab(url=None) - Open a new tab and optionally navigate it to a URL
switch_tab(handle) - Switch to a tab using a handle returned by list_tabs
close_tab(handle=None) - Close a specific tab, or the active tab when no handle is provided
take_screenshot(file_name, directory="tmp/selenium-screenshot") - Take a screenshot of the active tab. A descriptive file_name is required; .png is added when omitted. When the Agent knows its current workspace path, it should prefer an absolute directory inside that workspace so the destination does not depend on the MCP server cwd. Otherwise, omit directory to use the configured workspace default. Existing files receive a numeric suffix instead of being overwritten.

3.2. Element Interaction

get_an_element(text, class_name, id, attributes, element_type, in_iframe_id, in_iframe_name, return_html, xpath) - Get an element identified by various criteria
get_elements(text, class_name, id, attributes, element_type, in_iframe_id, in_iframe_name, page, page_size, return_html, xpath) - Get multiple elements with pagination support
get_direct_children(text, class_name, id, attributes, element_type, in_iframe_id, in_iframe_name, return_html, xpath, page, page_size) - Get all direct child nodes of an element with pagination
click_to_element(text, class_name, id, attributes, element_type, in_iframe_id, in_iframe_name, element_index, xpath) - Click on an element identified by various criteria
set_value_to_input_element(text, class_name, id, attributes, element_type, input_value, in_iframe_id, in_iframe_name, xpath) - Set a value to an input element

3.3. Element Styling

get_style_an_element(text, class_name, id, attributes, element_type, in_iframe_id, in_iframe_name, return_html, xpath, all_styles, computed_style) - Get style information for an element

3.4. JavaScript Execution

run_javascript_in_console(javascript_code) - Execute JavaScript without intentionally reading buffered console logs
run_javascript_and_get_console_output(javascript_code) - Drain old console logs, execute JavaScript, then return its value and newly captured console output

3.5. Browser Logs

get_console_logs(log_level) - Read and consume browser console logs with optional level filtering
get_network_logs(filter_url_by_text, only_errors_log) - Read and consume performance logs as network events with optional filtering
get_response(request_id) - Retrieve a response body using a request ID from get_network_logs

3.6. Local Storage Management

local_storage_add(key, string_value, object_value, create_empty_string, create_empty_object) - Add or update a key-value pair in browser's local storage
local_storage_read(key) - Read a value from browser's local storage by key
local_storage_read_all() - Read all key-value pairs from browser's local storage
local_storage_remove(key) - Remove a key-value pair from browser's local storage
local_storage_remove_all() - Remove all key-value pairs from browser's local storage

3.7. Compact Profile (Default)

The compact profile is the default and exposes the same browser capabilities through 10 tools and a smaller tools/list payload. It remains under evaluation; use --tool-profile legacy when an existing client still depends on the original 23 names. Legacy removal, if ever planned, will be announced as a separate breaking lifecycle change. Legacy names are not advertised as compact aliases because aliases would keep their schemas in Agent context.

Start it with:

python -m mcp_server_selenium

# Explicit compatibility fallback
python -m mcp_server_selenium --tool-profile legacy

All compact calls share one browser session and global active tab. A reliable default workflow is:

tabs(list) -> navigate -> wait_for -> query_elements -> interact_element -> take_screenshot

Use only fields relevant to an action. The 23 legacy names map to compact as follows:

Legacy tool	Compact call
`navigate(url, timeout)`	`navigate(url, wait_until="complete", timeout=timeout)`
`list_tabs()`	`tabs(action="list")`
`open_tab(url)`	`tabs(action="open", url=url)`
`switch_tab(handle)`	`tabs(action="switch", handle=handle)`
`close_tab(handle)`	`tabs(action="close", handle=handle)`
`take_screenshot(file_name, directory)`	`take_screenshot(file_name, directory, mode="viewport")`
`check_page_ready(wait_seconds)`	`wait_for(condition="ready", state="complete")`
`get_console_logs(log_level)`	`browser_logs(action="console", log_level=log_level)`
`get_network_logs(filter_url_by_text, only_errors_log)`	`browser_logs(action="network", filter_url_by_text=..., only_errors_log=...)`
`get_response(request_id)`	`browser_logs(action="response", request_id=request_id)`
`local_storage_add(...)`	`local_storage(action="add", key=..., string_value=... or object_value=...)`
`local_storage_read(key)`	`local_storage(action="read", key=key)`
`local_storage_remove(key)`	`local_storage(action="remove", key=key)`
`local_storage_read_all()`	`local_storage(action="read_all")`
`local_storage_remove_all()`	`local_storage(action="remove_all")`
`get_an_element(...)`	`query_elements(action="one", selector=...)`
`get_elements(...)`	`query_elements(action="many", selector=...)`
`get_direct_children(...)`	`query_elements(action="children", selector=...)`
`click_to_element(...)`	Query, then `interact_element(action="click", element_ref=...)`
`set_value_to_input_element(...)`	Query, then `interact_element(action="set_value", element_ref=..., input_value=...)`
`run_javascript_in_console(javascript_code)`	`run_javascript(javascript_code)`
`run_javascript_and_get_console_output(javascript_code)`	`run_javascript(javascript_code, capture_console=true)`
`get_style_an_element(...)`	Query, then `get_element_style(element_ref=...)`

Compact quick example

Each line is one JSON arguments object for the workflow step in the same order:

{"action":"list"}
{"url":"https://example.com","wait_until":"network_idle","timeout":30,"quiet_ms":500}
{"condition":"element","state":"visible","selector":{"type":"css","value":"#login"},"timeout":10}
{"action":"one","selector":{"type":"css","value":"#login"}}
{"action":"click","element_ref":"el_VALUE_FROM_QUERY"}
{"file_name":"login-result","mode":"full_page"}

tabs(action="list") also reports the active handle, URL/title/readyState of every tab, Chrome and ChromeDriver versions, and the absolute download directory. open activates its new tab; switch requires a listed handle; close accepts a handle or the active tab but never the final tab. Serialize tab-sensitive calls.

Selectors, waits, and referenc

…

Selenium

Installation

Configuration

How to use

README