selenium-mcp-server

DagiiM/selenium-mcp-server

3.1

If you are the rightful owner of selenium-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Selenium MCP Server is an autonomous, self-managing server designed for comprehensive UI analysis and intelligent browser automation.

Tools
5
Resources
0
Prompts
0

Selenium MCP Server

An autonomous, self-managing Selenium-based MCP (Model Context Protocol) server that provides comprehensive UI analysis, cross-browser testing, and intelligent browser automation with zero-configuration setup.

  • Self-initializing and self-healing
  • Multi-browser orchestration (Chrome, Firefox, Edge)
  • Performance, accessibility, responsive, and visual analysis
  • Quality scoring and actionable recommendations
  • Reports with logs and annotated screenshots

Table of Contents

  • Overview
  • Quick Start
  • Analyze Your Local Site (127.0.0.1:8000)
  • Available Tools (API Reference)
  • Configuration
  • Reports & Artifacts
  • Development
  • Testing
  • System Requirements
  • Troubleshooting
  • FAQ
  • License & Support

Overview

This MCP server exposes a suite of automation and analysis tools over the MCP stdio transport. It manages WebDriver installation, launches browsers, navigates to URLs, and runs comprehensive audits (performance, accessibility, cross-browser consistency, responsive design), returning structured results and generating reports.

Key capabilities

  • Autonomous setup: driver install, browser configuration, environment readiness
  • Multi-browser orchestration: parallel instances with health monitoring
  • Smart navigation: stability detection and dynamic content waiting
  • Comprehensive analysis: performance + accessibility + responsive + visual
  • Recommendations: prioritized, actionable fixes
  • Reporting: HTML/JSON artifacts, screenshots, and logs

Quick Start

Prerequisites

  • Node.js 18+ LTS
  • Ubuntu 20.04+ recommended (works on WSL/Ubuntu)

Install and run

# From project root
npm install
npm start

This builds and starts the MCP server using stdio transport. Use an MCP-capable client (e.g., an IDE integration or assistant) to call tools.

Development mode

npm run dev

Hot-reloads the server for local development.

Analyze Your Local Site (127.0.0.1:8000)

Run your site

Start the MCP server

npm start

Call tools from an MCP client

  1. Autonomous setup
  • Tool: autonomous_setup
  • Example arguments:
    • browsers: ["chrome", "firefox"]
    • auto_install: true
    • optimize_for: "quality_analysis"
    • headless: true
  1. One-shot comprehensive analysis
  • Tool: comprehensive_analysis
  • Example arguments:
    • url: "http://127.0.0.1:8000"
    • analysis_types: ["accessibility", "performance", "responsive", "cross_browser"]
    • viewports: ["mobile", "tablet", "desktop", "wide"]
    • generate_report: true
    • auto_annotations: true
  1. Granular flow (optional)
  • start_browser: { browser: "chrome", headless: true, viewport: { width: 1366, height: 768 }, enable_monitoring: true }
  • navigate: { url: "http://127.0.0.1:8000", wait_for: "network_idle", timeout: 30000 }
  • performance_audit: { url: "http://127.0.0.1:8000", generate_report: true }
  • accessibility_audit: { url: "http://127.0.0.1:8000", annotate: true }
  • capture_analysis: { url: "http://127.0.0.1:8000", viewport: "desktop" }

Notes

  • The server communicates over stdio as an MCP server; it is not an HTTP API.
  • Headless defaults to true. Set headless: false to observe browsers visually.

Available Tools (API Reference)

The following tools are exposed by the server. Names and behavior are defined in the server implementation.

  • autonomous_setup

    • Purpose: Prepare environment, install drivers, configure browsers
    • Args:
      • browsers: string[] (e.g., ["chrome", "firefox", "edge"]; default includes all)
      • auto_install: boolean (default: true)
      • optimize_for: "quality_analysis" | "speed" | "compatibility" (default: "quality_analysis")
      • headless: boolean (default: true)
    • Returns: { success, message, details, recommendations }

  • start_browser

    • Purpose: Start and register a browser instance
    • Args:
      • browser: "chrome" | "firefox" | "edge" (required)
      • viewport: { width: number; height: number } (min 320x240)
      • headless: boolean (default: true)
      • enable_monitoring: boolean (default: true)
    • Returns: { success, browserId, browser, viewport, status }

  • navigate

    • Purpose: Navigate to a URL with robust waiting
    • Args:
      • url: string (uri)
      • wait_for: "dom_ready" | "load_complete" | "network_idle" | "custom" (default: "dom_ready")
      • timeout: number (ms, 1000..60000)
    • Returns: { success, metrics?, status }

  • comprehensive_analysis

    • Purpose: Full UI quality audit across performance, accessibility, responsive, and cross-browser checks
    • Typical Args:
      • url: string (uri)
      • analysis_types: string[] (e.g., ["accessibility", "performance", "responsive", "cross_browser"])
      • viewports: string[] or custom viewport sizes (e.g., ["mobile", "tablet", "desktop", "wide"])
      • generate_report: boolean
      • auto_annotations: boolean
    • Returns: AnalysisResult including qualityScore, recommendations, and artifacts

  • find_element

    • Purpose: Enhanced element discovery with context
    • Args: { selector: string, strategy?: "css" | "xpath" | "id" | "className" | "name" | "tagName" }
    • Returns: { success, found, selector, elementInfo? }

  • interact_element

    • Purpose: Interaction simulation with validation
    • Args: { selector: string, action: "click" | "hover" | ..., validate?: boolean }
    • Returns: { success, metrics }

  • extract_content

    • Purpose: Extract and analyze page content
    • Args: { selector?: string, include_metadata?: boolean }
    • Returns: { success, content, analysis }

  • capture_analysis

    • Purpose: Screenshot with annotations
    • Args: { url?: string, viewport?: string|{width:number;height:number}, annotations?: boolean }
    • Returns: { success, path, notes }

  • performance_audit

    • Purpose: Measure Core Web Vitals and related metrics
    • Args: { url: string, generate_report?: boolean }
    • Returns: { success, performance, score }

  • accessibility_audit

    • Purpose: Axe-core backed WCAG testing
    • Args: { url: string, annotate?: boolean }
    • Returns: { success, accessibility, violations }

Refer to src/server.ts for the authoritative schemas and behavior.

Configuration

Installation Methods

The Selenium MCP Server can be installed and configured in multiple ways depending on your editor and workflow preferences:

Method 1: Direct GitHub Installation
# Clone and install from GitHub
git clone https://github.com/DagiiM/selenium-mcp-server.git
cd selenium-mcp-server
npm install
npm start
Method 2: NPM Package (when published)
# Install from npm registry
npm install -g @eleso/selenium-mcp-server
selenium-mcp-server
Method 3: NPX Direct from GitHub
# Run directly from GitHub without local installation
npx git+https://github.com/DagiiM/selenium-mcp-server.git

VSCode & MCP Configuration

For optimal development experience and to leverage the full capabilities of the Selenium MCP Server, configure your VSCode environment as follows:

Option A: GitHub-based Configuration (Recommended)

Add to your VSCode MCP settings or .vscode/settings.json:

{
  "mcp.servers": {
    "selenium-mcp-server": {
      "command": "npx",
      "args": ["git+https://github.com/DagiiM/selenium-mcp-server.git"],
      "env": {},
      "autoStart": true
    }
  }
}
Option B: Local Installation Configuration

If you've cloned the repository locally:

{
  "mcp.servers": {
    "selenium-mcp-server": {
      "command": "npm",
      "args": ["start"],
      "cwd": "./selenium-mcp-server",
      "env": {},
      "autoStart": true
    }
  }
}
Option C: NPM Package Configuration

When installed via npm:

{
  "mcp.servers": {
    "selenium-mcp-server": {
      "command": "npx",
      "args": ["@eleso/selenium-mcp-server"],
      "env": {},
      "autoStart": true
    }
  }
}
VSCode Extensions & Settings

  1. Required Extensions:

    • MCP Extension: Install the official MCP VSCode extension for seamless interaction
    • TypeScript and ESLint Extensions: For code highlighting, linting, and type checking

  2. Recommended VSCode Settings (settings.json):

    {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "eslint.validate": ["javascript", "typescript"],
    "typescript.tsdk": "node_modules/typescript/lib",
    "[typescript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[javascript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    }
}

Trae Configuration

To integrate the Selenium MCP Server with Trae, choose one of the following configurations:

Option A: GitHub Direct Installation (Recommended)

Add to your Trae configuration file (.trae/config.json):

{
  "mcpServers": {
    "SeleniumMCP": {
      "command": "npx",
      "args": ["git+https://github.com/DagiiM/selenium-mcp-server.git"],
      "env": {},
      "autoInstall": true,
      "autoStart": true
    }
  }
}
Option B: Local Repository Configuration

For local development or when you've cloned the repository:

{
  "mcpServers": {
    "SeleniumMCP": {
      "command": "npm",
      "args": ["start"],
      "cwd": "./selenium-mcp-server",
      "env": {},
      "autoStart": true
    }
  }
}
Option C: NPM Package Configuration

When using the published npm package:

{
  "mcpServers": {
    "SeleniumMCP": {
      "command": "npx",
      "args": ["@eleso/selenium-mcp-server"],
      "env": {},
      "autoInstall": true,
      "autoStart": true
    }
  }
}

Advanced Configuration Options

Custom Environment Variables
{
  "mcpServers": {
    "SeleniumMCP": {
      "command": "npx",
      "args": ["git+https://github.com/DagiiM/selenium-mcp-server.git"],
      "env": {
        "ANALYSIS_REPORT_DIR": "./custom-reports",
        "ANALYSIS_SCREENSHOT_DIR": "./custom-screenshots",
        "TEST_BASE_URL": "http://localhost:3000"
      },
      "autoStart": true
    }
  }
}
Browser-Specific Configuration
{
  "mcpServers": {
    "SeleniumMCP": {
      "command": "npx",
      "args": ["git+https://github.com/DagiiM/selenium-mcp-server.git"],
      "env": {
        "DEFAULT_BROWSER": "chrome",
        "HEADLESS_MODE": "true",
        "ENABLE_MONITORING": "true"
      },
      "autoStart": true
    }
  }
}

Environment variables (selected)

  • TEST_BASE_URL: Centralized base URL for tests (default: https://example.com). Overrides integration tests’ target URL.
  • ANALYSIS_REPORT_DIR: Output directory for analysis reports (default: ./reports/analysis)
  • ANALYSIS_SCREENSHOT_DIR: Output directory for screenshots (default: ./reports/screenshots)
  • Headless and browser-related options are provided via tool arguments rather than env in most cases.

TypeScript

  • Strict TypeScript, ES modules, and ESM-aware Jest config.

Project scripts

npm run dev           # Start in watch mode (tsx)
npm run build         # Compile TypeScript to dist/
npm start             # Build (prestart) then run from dist/
npm run test:unit     # Unit tests
npm run test:integration  # Integration tests
npm test              # Full test suite
npm run lint          # ESLint on src/ and tests/
npm run type-check    # tsc --noEmit
npm run install:drivers # Install WebDrivers

Reports & Artifacts

  • Reports: ./reports/analysis
  • Screenshots: ./reports/screenshots
  • Logs: ./reports/logs The server and tests ensure these directories exist; artifacts are generated when you request reports in tool calls.

Development

Structure

src/
  core/
    autonomous-setup.ts
    browser-orchestrator.ts
    ui-analysis-engine.ts
  server.ts
  types/
    index.ts

tests/
  unit/
  integration/
  config/

Guidelines

  • Minimal dependencies, first-principles architecture
  • Comprehensive tests for new features
  • Keep tools’ input/output stable and documented
  • Ensure artifacts are reproducible and paths are centralized

Testing

Run tests

npm test

Scope

  • Unit tests: core logic and utilities
  • Integration tests: end-to-end flows and tool behavior

Override test target URL

TEST_BASE_URL="http://127.0.0.1:8000" npm test

System Requirements

  • OS: Ubuntu 20.04+ (WSL/Ubuntu supported)
  • Node.js: 18+
  • RAM: 4GB+ for multi-browser analysis
  • Browsers: Chrome/Chromium, Firefox, Edge (latest stable)

Troubleshooting

WebDriver installation fails

npm run install:drivers
# or install with apt for chromium and firefox drivers
sudo apt-get update
sudo apt-get install chromium-chromedriver firefox-geckodriver

Browser crashes or runs out of memory

  • Reduce parallelism; run fewer concurrent browsers
  • Use headless: true for stability
  • Ensure swap is configured if RAM is limited

Navigation or analysis timeouts

  • Increase timeout in tool args (e.g., navigate.timeout)
  • Verify the target URL is reachable from the environment
  • Check network conditions and content security policies

FAQ

Is this an HTTP server?

  • No. It is an MCP server over stdio. Use an MCP-compatible client to call tools.

Can it run against localhost sites?

Where are reports stored?

  • ./reports/analysis by default, alongside screenshots and logs under ./reports/.

How do I change test target URLs?

  • Set TEST_BASE_URL before running tests. Tests use a single source of truth.

License & Support

License: MIT (see LICENSE)

Support

Maintained by Eleso Solutions.