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

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

// 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 'john@example.com'"

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.

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

Keywords

mcp

model-context-protocol

FAQs

What is selenium-mcp-server?

Is selenium-mcp-server popular?

Is selenium-mcp-server well maintained?

Package last updated on 01 Jun 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

selenium-mcp-server