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
• Quick Start
• Getting Started
• Client Integration
• Available Tools & Examples
• Advanced Configuration
• Environment Variables
• Testing Your Configuration
• FAQ / Troubleshooting
• Contributing
• Changelog
• Project Structure
• License
• 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

pip install selenium-mcp-server
python -m selenium_mcp_server

Add this to your MCP client config (e.g., Cursor AI):

{
  "mcpServers": {
    "selenium": {
      "command": "python",
      "args": ["-m", "selenium_mcp_server"]
    }
  }
}

🏁 Getting Started

1. Install

   pip install selenium-mcp-server
   

2. Run the server

   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

  { "browser": "chrome", "options": { "headless": true } }
  

• List Sessions

  { "name": "list_sessions", "arguments": {} }
  

• Switch Session

  { "session_id": "your-session-id" }
  

• Close Session

  { "session_id": "your-session-id" }
  

Navigation & Page Info

• Navigate

  { "url": "https://example.com", "wait_for_load": true }
  

• Get Page Info

  { "include_title": true, "include_url": true, "include_source": false }
  

Element Interaction

• Find Element

  { "selector": "#my-element", "selector_type": "css" }
  

• Click Element

  { "selector": "#my-button", "selector_type": "css", "force_click": true }
  

• Send Keys

  { "selector": "#input", "selector_type": "css", "text": "hello", "clear_first": true }
  

• Get Element Text

  { "selector": "#output", "selector_type": "css" }
  

• Hover

  { "selector": "#hover-target", "selector_type": "css" }
  

• Drag and Drop

  { "selector": "#source", "selector_type": "css", "target_selector": "#target", "target_selector_type": "css" }
  

• Double Click / Right Click

  { "selector": "#element", "selector_type": "css" }
  

• Press Key

  { "key": "Enter" }
  

• Upload File

  { "selector": "input[type='file']", "selector_type": "css", "filePath": "C:/Users/YourName/file.txt" }
  

• Wait for Element

  { "selector": "#wait-for-me", "selector_type": "css", "wait_for_visible": true }
  

Advanced Actions

• Take Screenshot

  { "full_page": true }
  

• Execute Script

  { "script": "return document.title;" }
  

📊 Example Automation Flow

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)

{
  "mcpServers": {
    "selenium": {
      "command": "python",
      "args": ["-m", "selenium_mcp_server"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Option 2: Direct File Execution

• Windows:

  {
    "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:

  {
    "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

{
  "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:

{
  "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:

  python -c "import selenium_mcp_server; print('Module found!')"
  

• Check if the entry point works:

  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