# Selenium MCP Server 🚀

[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8%2B-blue.svg)](https://www.typescriptlang.org/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Standard-orange.svg)](https://modelcontextprotocol.io/)
[![Selenium WebDriver](https://img.shields.io/badge/Selenium-4.29%2B-43B02A.svg)](https://www.selenium.dev/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A production-grade **Model Context Protocol (MCP)** server providing comprehensive browser automation capabilities powered by **Selenium WebDriver** communicating over standard I/O (**`stdio`**).

Designed for seamless integration with LLMs, AI agents, and IDEs including **Antigravity IDE**, **Claude Desktop**, **Cursor**, **Windsurf**, and any MCP-compliant client.

---

## 🌟 Key Highlights

- ⚡ **Multi-Browser Support**: Chrome, Firefox, Microsoft Edge (headless or visible window).
- 🎯 **Intelligent Locators**: CSS Selectors, XPath, ID, Name, Tag, Class, Exact Text, and Partial Text matching.
- 🖱️ **Full Interaction Suite**: Click, type/fill, clear, hover, dropdown selection, keyboard shortcuts, and form submissions.
- 📸 **Visual Intelligence**: Full viewport screenshots or element-level screenshots returned directly as PNG images.
- 🧠 **Smart Content Extraction**: Clean text, full HTML source, or interactive semantic DOM structures tailored for LLM reasoning.
- 🛡️ **Advanced Automation**: Explicit wait conditions, JavaScript execution in page context, multi-tab switching, frame switching, and cookie session management.
- 🤖 **Auto Driver Management**: Utilizes Selenium 4+ built-in driver management (no manual driver installation required).

---

## 🎬 Demo

<p align="center">
  <video src="https://github.com/AbyvargheseMandapathel/Selenium-MCP-Server/raw/main/demo.mp4" controls="controls" width="100%"></video>
</p>

https://github.com/AbyvargheseMandapathel/Selenium-MCP-Server/raw/main/demo.mp4

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                 AI Agent / MCP Client                       │
│      (Claude Desktop / Antigravity IDE / Cursor)            │
└─────────────────────────────┬───────────────────────────────┘
                              │ stdio (JSON-RPC 2.0)
┌─────────────────────────────▼───────────────────────────────┐
│              Selenium MCP Server (Node.js/TS)               │
│                                                             │
│  ├── WebDriverManager (Session lifecycle, locators, auto-exit)
│  ├── Browser Tools    (launch, navigate, history, resize)   │
│  ├── Interaction Tools(click, fill, hover, select, keys)    │
│  ├── Content Tools    (extract, inspect, screenshot)        │
│  └── Advanced Tools   (scripting, waits, tabs, cookies)     │
└─────────────────────────────┬───────────────────────────────┘
                              │ WebDriver Wire Protocol / CDP
┌─────────────────────────────▼───────────────────────────────┐
│              Browser (Chrome / Edge / Firefox)              │
└─────────────────────────────────────────────────────────────┘
```

---

## 📋 Prerequisites

- **Node.js**: v18.0.0 or higher ([Download Node.js](https://nodejs.org/))
- **Web Browser**: At least one supported browser installed (Google Chrome, Firefox, or Microsoft Edge).

---

## 📦 Installation & Build

1. Clone or navigate to the project directory:
   ```bash
   cd "c:/Users/ABY/Desktop/project/selenium - mcp"
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Build the TypeScript source to JavaScript (`dist/`):
   ```bash
   npm run build
   ```

4. *(Optional)* Run the automated smoke test to verify stdio communication:
   ```bash
   npm run test:smoke
   ```

---

## ⚙️ MCP Client Configuration

### 1. Antigravity IDE / Gemini IDE

Add the server to your `.agents/mcp_config.json` or global config:

```json
{
  "mcpServers": {
    "selenium": {
      "command": "node",
      "args": ["c:/Users/ABY/Desktop/project/selenium - mcp/dist/index.js"],
      "env": {
        "SELENIUM_HEADLESS": "false",
        "SELENIUM_BROWSER": "chrome"
      }
    }
  }
}
```

### 2. Claude Desktop

Add to `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "selenium": {
      "command": "node",
      "args": ["c:/Users/ABY/Desktop/project/selenium - mcp/dist/index.js"],
      "env": {
        "SELENIUM_HEADLESS": "false"
      }
    }
  }
}
```

---

## 👁️ Headless vs. Visible (Headful) Mode

You can control whether the browser runs in the background (headless) or opens as a visible window on your screen:

### Option A: Via AI Prompt / Tool Call
Simply ask your AI agent to run in visible or headless mode:
- **Visible mode**: The agent calls `launch_browser({ headless: false })` — Chrome/Edge/Firefox will pop up on your desktop so you can watch live clicks and typing.
- **Headless mode**: The agent calls `launch_browser({ headless: true })` — Runs silently in the background with zero desktop interruption.

### Option B: Server-Wide Default (via `env`)
Set the environment variable `SELENIUM_HEADLESS` in your MCP client config:
- `"SELENIUM_HEADLESS": "false"`: All browser sessions open as visible windows by default.
- `"SELENIUM_HEADLESS": "true"` *(default)*: All sessions run silently in headless mode.


### 3. Cursor

In Cursor Settings -> **Features** -> **MCP Servers** -> **Add New MCP Server**:
- **Name**: `selenium`
- **Type**: `command`
- **Command**: `node "c:/Users/ABY/Desktop/project/selenium - mcp/dist/index.js"`

---

## 🛠️ Complete Tools Reference

### 🌐 1. Browser Lifecycle & Navigation

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `launch_browser` | `browser` (`"chrome" \| "firefox" \| "edge"`)<br>`headless` (boolean, default: `true`)<br>`width`, `height` (integers)<br>`userAgent` (string)<br>`proxy` (string)<br>`args` (string array) | Launch a new browser session with custom viewport, flags, and configuration. |
| `close_browser` | *(none)* | Closes the active browser session and frees system resources. |
| `navigate` | `url` (string, required) | Navigates the browser to the specified URL. |
| `get_current_url` | *(none)* | Returns current page URL and document title. |
| `navigate_history` | `action` (`"back" \| "forward" \| "refresh"`) | Navigates backward/forward in history or reloads the page. |
| `set_window_size` | `width` (int), `height` (int) | Resizes the active browser window dimensions. |

---

### 🖱️ 2. User Interactions

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `click_element` | `selector` (string, req)<br>`strategy` (locator strategy)<br>`timeoutMs` (number) | Scrolls element into view, waits until clickable, and clicks it. |
| `fill_element` | `selector` (string, req)<br>`text` (string, req)<br>`strategy` (locator strategy)<br>`clearBefore` (bool, def: `true`)<br>`pressEnter` (bool, def: `false`) | Types text into an input field or textarea. |
| `clear_element` | `selector` (string, req)<br>`strategy` (locator strategy) | Clears all text from an input or textarea element. |
| `hover_element` | `selector` (string, req)<br>`strategy` (locator strategy) | Moves the mouse cursor over the target element. |
| `select_dropdown` | `selector` (string, req)<br>`selectBy` (`"value" \| "text" \| "index"`)<br>`optionValue` (string, req) | Selects an option inside a standard HTML `<select>` element. |
| `press_key` | `key` (`"ENTER" \| "TAB" \| "ESCAPE" \| "BACK_SPACE" \| "ARROWS" \| ...`)<br>`selector` (optional) | Sends special keyboard keys to the page or target element. |

---

### 🔍 3. Content Inspection & Visuals

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `get_page_content` | `format` (`"text" \| "html" \| "structure"`)<br>`maxLength` (number) | Extracts text, raw HTML, or interactive semantic DOM hierarchy. |
| `find_elements` | `selector` (string, req)<br>`strategy` (locator strategy)<br>`limit` (int, def: `20`) | Inspects matching elements and returns tag, text, classes, IDs, hrefs, and visibility. |
| `get_element_attribute` | `selector` (string, req)<br>`attributeName` (string, req)<br>`strategy` (locator strategy) | Reads an HTML attribute (e.g. `href`, `src`, `value`, `placeholder`, `aria-label`). |
| `take_screenshot` | `selector` (optional string)<br>`strategy` (optional) | Captures a high-resolution PNG screenshot of the full viewport or a specific element. |

---

### ⚡ 4. Advanced Execution & Flow

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `execute_script` | `script` (string, req)<br>`args` (array of any) | Runs custom JavaScript in the browser context with arguments and returns output. |
| `wait_for_element` | `selector` (string, req)<br>`strategy` (locator strategy)<br>`condition` (`"present" \| "visible" \| "clickable" \| "invisible"`)<br>`timeoutMs` (int) | Explicitly waits for an element to satisfy a condition. |
| `manage_tabs` | `action` (`"list" \| "switch" \| "new" \| "close"`)<br>`tabIndex` (number)<br>`url` (optional string) | Tab management: list open tabs, switch by index, create tab, or close current tab. |
| `manage_cookies` | `action` (`"get_all" \| "get" \| "set" \| "delete" \| "delete_all"`)<br>`name`, `value`, `domain`, `path`, `secure`, `httpOnly` | Full cookie session manipulation. |
| `switch_frame` | `target` (`"default" \| "parent" \| "element" \| "index"`)<br>`frameIndex` (int)<br>`selector` (string) | Changes driver execution context between iframes and parent documents. |

---

## 🎯 Locator Strategies Guide

When targeting elements, specify the `strategy` parameter:

| Strategy | Example Selector | Notes |
| :--- | :--- | :--- |
| `css` *(default)* | `#login-btn`, `.item:nth-child(2)`, `input[name='email']` | Standard CSS selector |
| `xpath` | `//div[@class='card'][contains(., 'Premium')]` | Full XPath 1.0 support |
| `id` | `username` | Matches `id="username"` |
| `name` | `password` | Matches `name="password"` |
| `text` | `Sign In` | Matches exact visible text |
| `partialText`| `Welcome back` | Matches substring of text |
| `class` | `btn-primary` | Matches class name |
| `tag` | `h1` | Matches HTML tag name |

---

## 💡 Example AI Automation Prompt

Once configured in your MCP client, you can give high-level automation instructions like:

> *"Launch Chrome in visible mode, go to https://news.ycombinator.com, find the top 5 articles, extract their titles and URLs, and take a screenshot of the top story."*

The LLM will automatically chain:
1. `launch_browser({ browser: "chrome", headless: false })`
2. `navigate({ url: "https://news.ycombinator.com" })`
3. `find_elements({ selector: ".titleline > a", strategy: "css", limit: 5 })`
4. `take_screenshot({ selector: ".athing:first-child", strategy: "css" })`

---

## 📂 Project Structure

```
selenium - mcp/
├── package.json              # Package metadata and scripts
├── tsconfig.json             # TypeScript configuration
├── mcp_config.example.json   # Ready-to-use client config
├── LICENSE                   # MIT License
├── README.md                 # Complete documentation
├── scripts/
│   └── smoke-test.js         # Automated stdio JSON-RPC smoke test
└── src/
    ├── index.ts              # Stdio server entry point
    ├── driver/
    │   └── manager.ts        # WebDriverManager lifecycle & locators
    └── tools/
        ├── index.ts          # Central MCP tool registration
        ├── browser.ts        # Browser launch, navigation & history
        ├── interaction.ts    # Click, type, hover, select, keys
        ├── content.ts        # Text, HTML, elements & screenshots
        └── advanced.ts       # JavaScript, waits, tabs, cookies, frames
```

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).