selenium-mcp-server 1.2.0
A powerful Model Context Protocol (MCP) server that brings Selenium WebDriver automation to AI assistants
License: MIT
Requires Python: >=3.8
Keywords: selenium, webdriver, automation, mcp, model-context-protocol, ai, assistant

# Selenium MCP Server

[![CI](https://github.com/krishnapollu/selenium-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/krishnapollu/selenium-mcp-server/actions/workflows/ci.yml)
[![PyPI version](https://badge.fury.io/py/selenium-mcp-server.svg)](https://badge.fury.io/py/selenium-mcp-server)
[![PyPI downloads](https://img.shields.io/pypi/dm/selenium-mcp-server.svg)](https://pypi.org/project/selenium-mcp-server/)
[![Python versions](https://img.shields.io/pypi/pyversions/selenium-mcp-server.svg)](https://pypi.org/project/selenium-mcp-server/)
[![License](https://img.shields.io/pypi/l/selenium-mcp-server.svg)](https://pypi.org/project/selenium-mcp-server/)

A powerful Model Context Protocol (MCP) server that brings Selenium WebDriver automation to AI assistants. This server enables AI tools like Claude Desktop and Cursor AI to control web browsers programmatically, making web automation accessible through natural language commands.

---

## 📚 Table of Contents
- [Features](#-features)
- [Quick Start](#-quick-start)
- [Getting Started](#-getting-started)
- [Client Integration](#-client-integration)
- [Available Tools & Examples](#-available-tools--examples)
- [Advanced Configuration](#-advanced-configuration)
- [Environment Variables](#-environment-variables)
- [Testing Your Configuration](#-testing-your-configuration)
- [FAQ / Troubleshooting](#-faq--troubleshooting)
- [Contributing](#-contributing)
- [Changelog](#-changelog)
- [Project Structure](#project-structure)
- [License](#license)
- [Contact & Support](#contact--support)

---

## 🚀 Features
- Multi-browser support: Chrome and Firefox (headless or full mode)
- Session management: Start, list, switch, and close browser sessions
- Navigation: Go to URLs, reload, and retrieve page info
- Element interaction: Find, click, type, hover, drag-and-drop, double/right click, upload files
- Advanced actions: Execute JavaScript, take screenshots, get/set element text
- File operations: Upload files, download files, take full-page screenshots
- Robust error handling
- Easy integration with any MCP-compatible client (Cursor AI, Claude Desktop, Google Gemini, etc.)
- PEP 517/518 compliant packaging

---

## ⚡ Quick Start

```bash
pip install selenium-mcp-server
python -m selenium_mcp_server
```

Add this to your MCP client config (e.g., Cursor AI):
```json
{
  "mcpServers": {
    "selenium": {
      "command": "python",
      "args": ["-m", "selenium_mcp_server"]
    }
  }
}
```

---

## 🏁 Getting Started

1. **Install**
   ```bash
   pip install selenium-mcp-server
   ```
2. **Run the server**
   ```bash
   python -m selenium_mcp_server
   ```
3. **Connect your MCP client** (see config above)

**Windows users:** If you see a `.exe.deleteme` error, delete any `selenium-mcp-server.exe` or `.exe.deleteme` files in your Python `Scripts` directory, then retry the install. You can always run the server with `python -m selenium_mcp_server`.

---

## 🤖 Client Integration

- **Cursor AI:** `~/.cursor/mcp_config.json`
- **Claude Desktop:** `~/.config/claude-desktop/config.json` (Linux/macOS) or `%APPDATA%\claude-desktop\config.json` (Windows)
- **Other MCP Clients:** See your client's documentation

---

## 🛠️ Available Tools & Examples

### Browser Management
- **Start Browser**
  ```json
  { "browser": "chrome", "options": { "headless": true } }
  ```
- **List Sessions**
  ```json
  { "name": "list_sessions", "arguments": {} }
  ```
- **Switch Session**
  ```json
  { "session_id": "your-session-id" }
  ```
- **Close Session**
  ```json
  { "session_id": "your-session-id" }
  ```

### Navigation & Page Info
- **Navigate**
  ```json
  { "url": "https://example.com", "wait_for_load": true }
  ```
- **Get Page Info**
  ```json
  { "include_title": true, "include_url": true, "include_source": false }
  ```

### Element Interaction
- **Find Element**
  ```json
  { "selector": "#my-element", "selector_type": "css" }
  ```
- **Click Element**
  ```json
  { "selector": "#my-button", "selector_type": "css", "force_click": true }
  ```
- **Send Keys**
  ```json
  { "selector": "#input", "selector_type": "css", "text": "hello", "clear_first": true }
  ```
- **Get Element Text**
  ```json
  { "selector": "#output", "selector_type": "css" }
  ```
- **Hover**
  ```json
  { "selector": "#hover-target", "selector_type": "css" }
  ```
- **Drag and Drop**
  ```json
  { "selector": "#source", "selector_type": "css", "target_selector": "#target", "target_selector_type": "css" }
  ```
- **Double Click / Right Click**
  ```json
  { "selector": "#element", "selector_type": "css" }
  ```
- **Press Key**
  ```json
  { "key": "Enter" }
  ```
- **Upload File**
  ```json
  { "selector": "input[type='file']", "selector_type": "css", "filePath": "C:/Users/YourName/file.txt" }
  ```
- **Wait for Element**
  ```json
  { "selector": "#wait-for-me", "selector_type": "css", "wait_for_visible": true }
  ```

### Advanced Actions
- **Take Screenshot**
  ```json
  { "full_page": true }
  ```
- **Execute Script**
  ```json
  { "script": "return document.title;" }
  ```

---

## 📊 Example Automation Flow

```mermaid
flowchart TD
  A["MCP Client (e.g., Cursor AI)"] -->|"Sends command"| B["Selenium MCP Server"]
  B -->|"Controls"| C["Web Browser (Chrome/Firefox)"]
  C -->|"Returns result"| B
  B -->|"Responds via MCP"| A
```

---

## ⚙️ Advanced Configuration

You can configure the Selenium MCP Server in several ways:

### Option 1: Installed Package (Recommended)
```json
{
  "mcpServers": {
    "selenium": {
      "command": "python",
      "args": ["-m", "selenium_mcp_server"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

### Option 2: Direct File Execution
- **Windows:**
  ```json
  {
    "mcpServers": {
      "selenium": {
        "command": "python",
        "args": ["C:\\path\\to\\selenium-mcp-server\\src\\selenium_mcp_server.py"],
        "env": {
          "PYTHONPATH": "C:\\path\\to\\selenium-mcp-server\\src",
          "PYTHONUNBUFFERED": "1"
        }
      }
    }
  }
  ```
- **macOS/Linux:**
  ```json
  {
    "mcpServers": {
      "selenium": {
        "command": "python",
        "args": ["/path/to/selenium-mcp-server/src/selenium_mcp_server.py"],
        "env": {
          "PYTHONPATH": "/path/to/selenium-mcp-server/src",
          "PYTHONUNBUFFERED": "1"
        }
      }
    }
  }
  ```

### Option 3: Console Script
```json
{
  "mcpServers": {
    "selenium": {
      "command": "selenium-mcp-server"
    }
  }
}
```

---

## 🌐 Environment Variables
- `PYTHONUNBUFFERED=1`: Ensures Python output is not buffered
- `SELENIUM_LOG_LEVEL=INFO`: Sets logging level (DEBUG, INFO, WARNING, ERROR)
- `PYTHONPATH`: Points to the directory containing the Python modules (needed for direct file execution)

---

## 🧪 Testing Your Configuration
After configuring, test with:
```json
{
  "name": "list_sessions",
  "arguments": {}
}
```
You should get an empty list if no sessions are active.

---

## ❓ FAQ / Troubleshooting

**Q: I see "0 tools enabled" in Cursor AI.**
- Make sure the package is installed: `pip install selenium-mcp-server` (or `pip install -e .` for development)
- Verify the module works:
  ```bash
  python -c "import selenium_mcp_server; print('Module found!')"
  ```
- Check if the entry point works:
  ```bash
  selenium-mcp-server --help
  ```
- Try using the console script entry point in your config.

**Q: "Module not found" errors**
- Make sure you've installed the package: `pip install selenium-mcp-server` or `pip install -e .`
- Check that the `PYTHONPATH` points to the correct directory if running from source
- Verify the file paths are correct for your system

**Q: "Command not found" errors**
- Ensure Python is in your system PATH
- Try using the full path to Python: `C:\Python312\python.exe` (Windows) or `/usr/bin/python3` (Linux/macOS)

**Q: Permission errors**
- On Windows, try running your MCP client as administrator
- On Linux/macOS, check file permissions: `chmod +x src/selenium_mcp_server.py`