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

Related MCP server: visual-ui-debug-agent-mcp

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

• Ensure your app is reachable at http://127.0.0.1:8000 (Django/DRF defaults to 8000).

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

2. 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

3. 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?

• Yes. Use http://127.0.0.1:8000 (or http://localhost:8000) and ensure it’s reachable from the server environment.

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

• Email: support@ifinsta.com

• Issues: https://github.com/eleso/selenium-mcp-server/issues

Maintained by Eleso Solutions.