Selenium Self-Healing MCP Server

December 19, 2025 ยท View on GitHub

An MCP server that automatically fixes broken Selenium test locators when UI changes occur, reducing test maintenance overhead.

Overview

When web UI changes break your automated tests, this MCP server intelligently finds alternative locators using multiple fallback strategies. Instead of failing immediately, it searches for elements by text content and visible attributes, returning the new working locator for future use.

Features

  • Smart Fallback: Tries original CSS selector, then text matching, then visible element discovery
  • Locator Return: Provides new working locators when originals fail
  • Zero Configuration: Works out of the box with Chrome 143
  • Container Isolated: Runs in secure Docker container
  • AI-Friendly: Designed for AI assistant integration

Tools

open

Navigate to a URL.

Parameters:

  • url (string, required): Target URL

Example:

{
  "url": "https://example.com"
}

Returns: Page title confirmation

click

Click an element with automatic self-healing.

Parameters:

  • locator (string, required): CSS selector
  • description (string, optional): Text description for fallback search

Example:

{
  "locator": "#submit-button",
  "description": "login button"
}

Returns:

  • Success: "Clicked!" or "Clicked! NEW LOCATOR: [new-selector]"
  • Failure: "Could not find element even with self-healing"

type

Type text into an input field with automatic self-healing.

Parameters:

  • locator (string, required): CSS selector
  • text (string, required): Text to type
  • description (string, optional): Text description for fallback search

Example:

{
  "locator": "#username",
  "text": "user@example.com",
  "description": "username field"
}

Returns:

  • Success: "Typed!" or "Typed! NEW LOCATOR: [new-selector]"
  • Failure: "Could not find element even with self-healing"

screenshot

Capture current page screenshot.

Parameters: None

Returns: Base64 encoded PNG image

How Self-Healing Works

When a locator fails, the server attempts three strategies in order:

  1. Original CSS Selector: Try the provided locator
  2. Text Search: Search clickable elements (links, buttons) for matching text
  3. Visible Element Discovery: Find any visible element with an ID attribute

If a fallback succeeds, the server returns the new working locator.

Installation

docker pull mcp/selenium-selfhealing-mcp

From Source

git clone https://github.com/aiqualitylab/selenium-selfhealing-mcp.git
cd selenium-selfhealing-mcp
docker build -t selenium-selfhealing-mcp .

Usage

With Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "selenium": {
      "command": "docker",
      "args": ["run", "-i", "mcp/selenium-selfhealing-mcp"]
    }
  }
}

Restart Claude Desktop to load the server.

With Other MCP Clients

Run the Docker container with stdio:

docker run -i mcp/selenium-selfhealing-mcp

The server communicates via stdin/stdout using MCP protocol.

Example Usage

User: Open example.com and click using CSS #wrong-id with description "more information"

AI: Opened: example.com
    Clicked! NEW LOCATOR: element

The server found the search button by text and returned the working selector.

Use Cases

  • Test Maintenance: Automatically adapt tests when UI changes
  • Exploratory Testing: Let AI discover correct locators through trial
  • Test Migration: Update old tests with broken selectors
  • CI/CD Resilience: Reduce flaky tests from minor UI changes

Requirements

  • Docker
  • Chrome 143+ (included in container)
  • Python 3.11+ (included in container)

Error Handling

All tools return clear error messages:

  • Network failures return connection errors
  • Missing elements return "Could not find element" message
  • Invalid URLs return navigation errors

Errors are logged but do not crash the server.

Security

  • Runs in isolated Docker container
  • No persistent storage of credentials
  • Chrome runs with security flags (--no-sandbox, --disable-dev-shm-usage)
  • No external network access except browsing

Limitations

  • Chrome-only (no Firefox/Safari support)
  • Headless mode only (no visual debugging)
  • Text search is case-insensitive English
  • Maximum 3 fallback strategies

Troubleshooting

Server won't start

  • Ensure Docker is running
  • Check port 9222 isn't in use
  • Verify Chrome installation in container

Elements not found

  • Provide descriptive text in description parameter
  • Wait for page load before clicking
  • Check if element is in iframe (not supported)

ChromeDriver version mismatch

  • Update to latest container image
  • Chrome and ChromeDriver versions are pinned together

Contributing

Issues and pull requests welcome at: https://github.com/aiqualitylab/selenium-selfhealing-mcp

License

MIT License - See LICENSE file

Author

aiqualitylab

Changelog

v1.0.0 (2025-12-12)

  • Initial release
  • Basic self-healing with 3 strategies
  • Chrome 143 support
  • Docker containerization