selenium-mcp-server

Selenium MCP Server

A Model Context Protocol (MCP) server that provides browser automation capabilities using Puppeteer. This server enables LLMs to interact with web pages through structured accessibility snapshots and real browser automation.

🚀 Key Features

• Real Browser Automation: Uses Puppeteer for actual browser control (not simulated)
• Team-Friendly: Visible browser by default so teams can see automation in action
• MCP Compliant: Follows MCP standards like Microsoft's Playwright MCP
• Local Dependencies: No global npm installation required
• Accessibility-First: Uses element snapshots for reliable automation

📋 Available Tools

• browser_navigate - Navigate to any URL
• browser_snapshot - Get page accessibility snapshot with element references
• browser_click - Click on elements using references from snapshots
• browser_type - Type text into form fields with optional submission
• browser_wait_for - Wait for time, text to appear, or text to disappear
• browser_take_screenshot - Capture screenshots of the current page

🛠️ Installation & Setup

For Cursor Users

• Add to Cursor Settings:

  • Go to Cursor Settings → MCP → Add new MCP Server
  • Name: selenium-mcp
  • Command type: command
  • Command: npx
  • Arguments: ["selenium-mcp-server@latest"]

• Alternative JSON Configuration:

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

For Other MCP Clients

Use the same configuration pattern with your MCP client:

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

Alternative Installation Methods

Click to see other installation options

Method 1: Local Installation

npm install selenium-mcp-server

Method 2: Global Installation

npm install -g selenium-mcp-server

Quick Start

🎯 Zero-Installation (Recommended)

1. Add Configuration

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "selenium": {
      "command": "npx",
      "args": [
        "selenium-mcp-server@latest",
        "--browser", "chrome"
      ]
    }
  }
}

2. Restart Cursor

• Quit Cursor completely
• Restart Cursor
• npx will automatically download and run the server

Alternative Setup Methods

Option A: Local Installation

1. Install in your project

npm install selenium-mcp-server

2. Configure Cursor

{
  "mcpServers": {
    "selenium": {
      "command": "node",
      "args": ["./node_modules/selenium-mcp-server/dist/index.js", "--browser", "chrome", "--headless"]
    }
  }
}

Option B: Global Installation

1. Install globally

npm install -g selenium-mcp-server

2. Configure Cursor

{
  "mcpServers": {
    "selenium": {
      "command": "selenium-mcp",
      "args": ["--browser", "chrome", "--headless"]
    }
  }
}

3. Use in Cursor

Ask Cursor to perform browser automation:

• "Navigate to google.com and take a screenshot"
• "Fill out the contact form on example.com"
• "Extract all links from the current page"

Configuration Options

selenium-mcp [options]

Options:
  --browser <browser>        Browser to use (chrome, firefox, edge, safari) (default: "chrome")
  --headless                 Run browser in headless mode
  --executable-path <path>   Path to browser executable
  --user-data-dir <path>     Path to user data directory
  --isolated                 Keep browser profile in memory
  --viewport-size <size>     Browser viewport size (e.g., 1280,720)
  --output-dir <path>        Path to directory for output files
  -h, --help                 Display help for command

Available Tools

Navigation

• browser_navigate - Navigate to URLs
• browser_navigate_back - Go back in history
• browser_navigate_forward - Go forward in history

Page Interaction

• browser_click - Click on elements
• browser_type - Type text into inputs
• browser_hover - Hover over elements
• browser_drag - Drag and drop elements
• browser_select_option - Select dropdown options
• browser_press_key - Press keyboard keys

Information Gathering

• browser_snapshot - Capture accessibility tree
• browser_take_screenshot - Take screenshots
• browser_network_requests - List network requests
• browser_console_messages - Get console messages

Tab Management

• browser_tab_list - List open tabs
• browser_tab_new - Open new tabs
• browser_tab_select - Switch tabs
• browser_tab_close - Close tabs

Utilities

• browser_wait_for - Wait for elements/text
• browser_file_upload - Upload files
• browser_handle_dialog - Handle alerts/dialogs
• browser_resize - Resize browser window
• browser_pdf_save - Save page as PDF

Usage Examples

Basic Navigation and Screenshot

// In Cursor, ask:
"Navigate to https://example.com and take a screenshot"

Form Interaction

// In Cursor, ask:
"Go to the contact page and fill out the form with name 'John Doe' and email '[e-mail]'"

Data Extraction

// In Cursor, ask:
"Visit the product page and extract all product names and prices"

Requirements

• Node.js 18+
• Java 11+ (for Selenium WebDriver)
• Browser drivers (automatically managed by WebDriverManager)

Configuration Examples

Local Development

{
  "mcpServers": {
    "selenium": {
      "command": "selenium-mcp",
      "args": ["--browser", "chrome"]
    }
  }
}

Headless Production

{
  "mcpServers": {
    "selenium": {
      "command": "selenium-mcp",
      "args": [
        "--browser", "chrome",
        "--headless",
        "--viewport-size", "1920,1080"
      ]
    }
  }
}

Custom Browser Path

{
  "mcpServers": {
    "selenium": {
      "command": "selenium-mcp",
      "args": [
        "--browser", "chrome",
        "--executable-path", "/path/to/chrome"
      ]
    }
  }
}

Troubleshooting

Browser Not Found

If you get browser not found errors:

• Install the browser (Chrome, Firefox, etc.)
• Use --executable-path to specify browser location
• Check that Java is installed and accessible

Permission Issues

On macOS, you might need to grant accessibility permissions:

• Go to System Preferences > Security & Privacy > Privacy
• Select "Accessibility"
• Add your terminal application

Memory Issues

For large pages or long-running sessions:

{
  "mcpServers": {
    "selenium": {
      "command": "selenium-mcp",
      "args": ["--isolated", "--headless"]
    }
  }
}

Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Add tests
• Submit a pull request

License

MIT License - see LICENSE file for details.

Related Projects

• Playwright MCP - Similar server using Playwright
• Model Context Protocol - The protocol specification
• Selenium WebDriver - The underlying browser automation framework