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
  • 3.1. Navigation and Page Management
  • 3.2. Element Interaction
  • 3.3. Element Styling
  • 3.4. JavaScript Execution
  • 3.5. Browser Logs
  • 3.6. Local Storage Management
• 4. Installation
  • 4.1. Prerequisites
  • 4.2. Installation Options
    • 4.2.1. Option A: Install as Python Package (Recommended)
    • 4.2.2. Option B: Run from Source Code
  • 4.3. Chrome Setup
• 5. Usage
  • 5.1. Running the MCP Server
    • 5.1.1. Option A: From Installed Package
    • 5.1.2. Option B: From Source Code
  • 5.2. Using MCP Inspector for Testing
    • 5.2.1. Start Inspector Server
    • 5.2.2. Access Inspector Interface
    • 5.2.3. Command Line Options
  • 5.3. Using with MCP Clients
    • 5.3.1. Configuration Examples
    • 5.3.2. Debug
• 6. Examples
  • 6.1. Basic Web Automation
  • 6.2. Advanced Usage
    • 6.2.1. JavaScript Examples
• 7. Logging
• 8. Troubleshooting
  • 8.1. Common Issues
    • 8.1.1. Installation-Related Issues
    • 8.1.2. Runtime Issues
    • 8.1.3. Configuration 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
• Tab Video Recording: Record one fixed tab or one MP4 that follows active-tab switches across selected tabs, optionally with a synthetic URL header
• 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 24 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.
• record_video(action, file_name="", directory="tmp/selenium-video", include_address=false, window_handle="", max_duration_seconds=600, window_handles=[]) - start records one fixed window_handle, one MP4 following switches among 2-4 window_handles, or the active tab when both are omitted. The selectors are mutually exclusive. Always call stop immediately after the final browser action; the finite deadline auto-finalizes only as a fallback. Paths follow screenshot rules and include_address=true adds a synthetic URL header.

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 11 tools and a smaller tools/list payload. It remains under evaluation; use --tool-profile legacy when an existing client still depends on the original 24 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 24 legacy names map to compact as follows: