selenium-mcp-server by mm541 - MCP Server

# Selenium MCP Server

Selenium MCP Server is a standalone Python application that exposes a comprehensive suite of Selenium browser automation commands as a **FastMCP** server.

This allows a language model, AI agent, or any other client capable of calling tools to control a web browser, perform complex web scraping, and automate web-based tasks by issuing natural language commands.

## 🚀 Features

- **Browser Lifecycle**: Open and close Chrome, Firefox, or Edge instances.
- **Full Navigation**: `goto`, `back`, `forward`, `refresh`, and URL/title inspection.
- **Element Interaction**: `click`, `type`, `clear`, `get_text`, `get_attribute`.
- **Advanced Actions**: `hover`, `drag_and_drop`, `right_click`, `double_click`, `execute_javascript`.
- **Complex Targets**: Handles alerts, iframes, and Shadow DOM elements.
- **Data Extraction**: Scrape full tables into JSON, list all links, and get page source.
- **Window & Tab Management**: Open, close, and list all tabs.
- **Cookies & Storage**: Full control over browser cookies.
- **Explicit Waits**: Wait for elements to be visible or clickable to handle dynamic pages.

## 🔧 Dependencies and Installation

### Dependencies

This program relies on several third-party Python libraries:

- `fastmcp` – For creating the tool server
- `mcp-json` – For the JSON tool-calling schema with FastMCP
- `selenium` – For browser automation
- `webdriver-manager` – For automatically managing browser drivers (optional with Selenium 4.6+)

Create a `requirements.txt` file with the following content:

```txt
fastmcp
mcp-json
selenium
webdriver-manager

Installation Steps

Option 1: Using uv (Recommended)

uv is an extremely fast Python package installer and virtual environment manager.

# 1. Create virtual environment
uv venv

# 2. Activate the environment
# macOS / Linux
source .venv/bin/activate
# Windows
.\.venv\Scripts\activate

# 3. Install dependencies
uv pip install -r requirements.txt

Option 2: Using venv + pip (Traditional)

# 1. Create virtual environment
# macOS / Linux
python3 -m venv venv
# Windows
python -m venv venv

# 2. Activate the environment
# macOS / Linux
source venv/bin/activate
# Windows
.\venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

Browser Drivers

Modern versions of Selenium (4.6.0+) include Selenium Manager, which automatically downloads the correct webdriver (chromedriver, geckodriver, etc.) for your locally installed browsers the first time you run the script. No manual driver installation is required.

⚡️ Usage

Run the main script to start the server:

python main.py

By default, the server runs all browsers in headless mode (no visible UI). This is configured in the BrowserManager class.

Example output:

Selenium MCP Server Starting...
Selenium MCP Server Running...
Supported Tools:
- open_browser, close_browser, goto_url, click_element, type_text, etc.

Running with a JSON Configuration (for mcp-json)

Add the server to your mcp-servers.json configuration:

{
  "mcpServers": {
    "Selenium Automation Server": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "path/to/your/selenium_mcp_server.py"
      ],
      "env": {},
      "transport": "stdio"
    }
  }
}

Replace path/to/your/selenium_mcp_server.py with the actual path to your server script.

🛠 Available Tools (API Reference)

Browser Lifecycle & Navigation

Function	Description
`open_browser(browser_selector)`	Opens a new browser instance (`firefox`, `chrome`, `edge`). Defaults to Firefox.
`close_browser()`	Closes the current browser instance and cleans up resources.
`is_browser_active()`	Checks if the current browser is active and responsive.
`goto_url(url)`	Navigates the browser to the specified URL.
`get_current_url()`	Returns the URL of the current page.
`get_title()`	Returns the title of the current page.
`refresh_page()`	Refreshes the current page.
`go_back()`	Simulates the browser Back button.
`go_forward()`	Simulates the browser Forward button.

Element Interaction

Function	Description
`click_element(strategy, selector)`	Clicks an element identified by strategy and selector.
`type_text(text, strategy, selector, ...)`	Types text into an input field (can clear first and press Enter).
`get_element_text(strategy, selector)`	Gets the visible text of an element.
`get_element_attribute(attribute, ...)`	Gets an attribute from an element (e.g., `href`, `src`).
`click_shadow_dom_element(host, element)`	Clicks an element inside Shadow DOM.
`double_click_element(strategy, selector)`	Performs a double-click on an element.
`right_click_element(strategy, selector)`	Performs a right-click (context click).
`hover_element(strategy, selector)`	Simulates hovering the mouse over an element.
`drag_and_drop(source_selector, target_selector, ...)`	Drags and drops an element.

Data & Information Extraction

Function	Description
`get_page_source()`	Returns the full HTML source of the current page's `<body>`.
`extract_table_data(strategy, selector)`	Extracts table data and returns it as JSON.
`list_links()`	Returns a JSON list of all unique links (text + href).

Frames, Alerts, and Tabs

Function	Description
`handle_alert(accept, input_text)`	Handles alert/prompt (accept/dismiss, send text).
`switch_to_frame(selector, strategy)`	Switches context to an iframe.
`switch_to_default_content()`	Returns context to the main document.
`open_new_tab(url)`	Opens a new tab and switches to it.
`close_current_tab()`	Closes the currently active tab.
`switch_tab(index)`	Switches to a tab by index.
`list_all_tabs()`	Returns a JSON list of all open tabs (title + URL).

Waits & Validation

Function	Description
`wait_for_element_visible(strategy, selector, timeout)`	Waits for element to be present and visible.
`wait_for_element_clickable(strategy, selector, timeout)`	Waits for element to be clickable.
`is_element_visible(strategy, selector)`	Checks if element is currently visible (non-blocking).
`is_element_enabled(strategy, selector)`	Checks if element is enabled (non-blocking).

Cookies & Storage

Function	Description
`get_cookies()`	Returns all cookies for the current domain as JSON.
`add_cookie(name, value, path)`	Adds a simple cookie to the current session.
`delete_all_cookies()`	Deletes all cookies for the current session.

Advanced & Visual

Function	Description
`execute_javascript(script)`	Executes custom JavaScript and returns the result.
`scroll_to(x, y)`	Scrolls the window to absolute coordinates.
`scroll_by(x, y)`	Scrolls the window by a specific amount.
`take_screenshot(filename)`	Takes a viewport screenshot (returns base64 if no filename).
`save_full_page_screenshot(filename)`	Attempts to capture the entire page.