Back to MCP Servers

Selenium

A Model Context Protocol server providing web automation capabilities through Selenium WebDriver

browser-automationautomation
By PhungXuanAnh
93Updated 2 weeks agoPython

Installation

npx -y selenium-mcp-server

Configuration

{
  "mcpServers": {
    "selenium-mcp-server": {
      "command": "npx",
      "args": ["-y", "selenium-mcp-server"]
    }
  }
}

How to use

  1. Run the installation command above (if needed)
  2. Open your Claude Code settings file (~/.claude/settings.json)
  3. Add the configuration to the mcpServers section
  4. Restart Claude Code to apply changes

README

View on GitHub

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

  • Web Navigation: Navigate to URLs with timeout control and page readiness checking
  • 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 full-page screenshots of the current browser window
  • 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 MCP server provides the following tools:

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
  • take_screenshot() - Take a screenshot of the current browser window

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 code in the browser console
  • run_javascript_and_get_console_output(javascript_code) - Execute JavaScript code and capture both return value and console output

3.5. Browser Logs

  • get_console_logs(log_level) - Retrieve console logs from the browser with optional filtering by log level
  • get_network_logs(filter_url_by_text, only_errors_log) - Retrieve network request logs from the browser with optional filtering

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

4. Installation

4.1. Prerequisites

  • Python 3.10 or higher
  • Chrome browser installed

4.2. Installation Options

You can use this MCP server in two ways:

4.2.1. Option A: Install as Python Package (Recommended)

Install directly from PyPI:

pip install mcp-server-selenium

Or using uv:

uv add mcp-server-selenium

4.2.2. Option B: Run from Source Code

  1. Clone this repository:
git clone https://github.com/PhungXuanAnh/selenium-mcp-server.git
cd selenium-mcp-server
  1. Install dependencies using uv:
uv sync

Or using pip with virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

4.3. Chrome Setup

The MCP server can work with Chrome in two ways:

  1. Connect to existing Chrome instance (recommended): Start Chrome with debugging enabled:
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
  1. Auto-start Chrome: The server can automatically start Chrome if no instance is found.

5. Usage

5.1. Running the MCP Server

5.1.1. Option A: From Installed Package

After installing via pip/uv, you can run the server directly:

# Basic usage with default settings
python -m mcp_server_selenium

# With custom Chrome debugging port and user data directory
python -m mcp_server_selenium --port 9222 --user_data_dir /tmp/chrome-debug

# With verbose logging
python -m mcp_server_selenium --port 9222 --user_data_dir /tmp/chrome-debug -v

# Using the installed command (if available)
selenium-mcp-server --port 9222 --user_data_dir /tmp/chrome-debug -v

5.1.2. Option B: From Source Code

When running from source, ensure the Python path includes the src directory:

# Navigate to the project directory
cd /path/to/selenium-mcp-server

# Activate virtual environment (if using one)
source .venv/bin/activate

# Run with proper Python path
PYTHONPATH=src python -m mcp_server_selenium --port 9222 --user_data_dir /tmp/chrome-debug -v

# Or using uv (recommended for development)
uv run python -m mcp_server_selenium --port 9222 --user_data_dir /tmp/chrome-debug -v

5.2. Using MCP Inspector for Testing

5.2.1. Start Inspector Server

For development and testing, you can use the MCP inspector:

From Source Code:

# Using uv (recommended)
uv run mcp dev src/mcp_server_selenium/__main__.py

# Or with make command
make inspector

# With custom options
uv run mcp dev src/mcp_server_selenium/__main__.py --port 9222 --user_data_dir /tmp/chrome-debug --verbose

From Installed Package:

# Create a wrapper script or use directly
mcp dev python -m mcp_server_selenium

5.2.2. Access Inspector Interface

Open your browser and navigate to: http://127.0.0.1:6274/#tools

Check logs:

tailf /tmp/selenium-mcp.log

5.2.3. Command Line Options

  • --port: Chrome remote debugging port (default: 9222)
  • --user_data_dir: Chrome user data directory (default: auto-generated in /tmp)
  • -v, --verbose: Increase verbosity (use multiple times for more details)

5.3. Using with MCP Clients

The server communicates via stdio and follows the Model Context Protocol specification. You can integrate it with MCP-compatible AI assistants or clients.

5.3.1. Configuration Examples

For Claude Desktop (claude_desktop_config.json):

Using installed package:

{
  "mcpServers": {
    "selenium": {
      "command": "python",
      "args": [
        "-m", "mcp_server_selenium",
        "--port", "9222",
        "--user_data_dir", "/tmp/chrome-debug-claude"
      ],
      "env": {}
    }
  }
}

For VS Code Copilot (.vscode/mcp.json):

Using installed package:

{
  "servers": {
    "selenium-installed": {
      "command": "python",
      "args": [
        "-m", "mcp_server_selenium",
        "--user_data_dir=/home/user/.config/google-chrome-selenium-mcp",
        "--port=9225"
      ]
    }
  }
}

Using source code directly:

{
  "servers": {
    "selenium-source": {
      "command": "/path/to/selenium-mcp-server/.venv/bin/python",
      "args": [
        "-m", "mcp_server_selenium",
        "--user_data_dir=/home/user/.config/google-chrome-selenium-mcp-source",
        "--port=9226"
      ],
      "env": {
        "PYTHONPATH": "/path/to/selenium-mcp-server/src"
      }
    }
  }
}

Alternative source code configuration using full path:

{
  "servers": {
    "selenium-source-alt": {
      "command": "/path/to/selenium-mcp-server/.venv/bin/python",
      "args": [
        "/path/to/selenium-mcp-server/src/mcp_server_selenium/__main__.py",
        "--user_data_dir=/home/user/.config/google-chrome-selenium-mcp-alt",
        "--port=9227"
      ]
    }
  }
}

5.3.2. Debug

VS Code Copilot MCP Status: If you open the .vscode/mcp.json file, you can see the MCP server status at the bottom of VS Code.

alt text

View MCP Logs:

  • In VS Code: Open Command Palette → "Developer: Show Logs..." → "MCP: selenium"
  • Check log file: tail -f /tmp/selenium-mcp.log

6. Examples

6.1. Basic Web Automation

  1. Navigate to a website:

    • Tool: navigate
    • URL: https://example.com

  2. **Take a s

…

View source on GitHub

You might also like

UI TARS Desktop
MCP Servers
Server Playwright
MCP Servers
Playwright Plus Python
MCP Servers