selenium-selfhealing

The Selenium Self-Healing MCP Server automatically fixes broken Selenium test locators when the UI changes. It exposes a small set of tools over the MCP protocol: open (navigate to a URL), click (attempt to click an element with automatic locator self-healing), type (type text into an input with healing), and screenshot (capture the current page as a Base64-encoded image). When a locator fails, the server tries three strategies in order: the original CSS selector, a text-based search for clickable elements, and then a visible element discovery by ID. If a suitable fallback is found, it returns a new working locator that your client can use going forward. This is designed to work best in Docker, running Chrome 143+ inside the container.

To use it with Claude Desktop or other MCP clients, you communicate via stdin/stdout using the MCP protocol. For example, you can configure Claude Desktop to contact the container image using a Docker run command or reference the server in your MCP client configuration. The server will respond with success messages like "Clicked! NEW LOCATOR: ..." or "Typed! NEW LOCATOR: ..." when a fallback locator is found, enabling your tests to adapt automatically to UI changes.

Prerequisites:

• Docker installed and running
• Internet access to pull the docker image (mcp/selenium-selfhealing-mcp)

Install steps:

1. Pull the official image (recommended):

docker pull mcp/selenium-selfhealing-mcp

2. Run the MCP server in interactive mode:

docker run -i mcp/selenium-selfhealing-mcp

3. (Optional) Integrate with Claude Desktop or another MCP client by pointing it to the Docker container via the standard MCP protocol (stdin/stdout). If your client requires a config entry, you can reference the image directly in the docker run command as shown above.

4. Verify the server is responding by sending a simple MCP command (e.g., open a URL) and confirming a response is returned.

Notes:

• The container includes Chrome 143 and runs with headless mode by default.
• Ensure port conflicts are avoided; the MCP server communicates over stdio when run with -i (interactive).
• If you prefer building locally, you can clone the repo and build the image from source (not required for standard use).

Tips and caveats:

• ChromeDriver and Chrome are pinned to versions inside the container; if you encounter compatibility issues, pull the latest image to get updated ChromeDriver support.
• The self-healing supports up to 3 fallback strategies: original CSS selector, text-based search for clickable elements, and visible element discovery by ID. If a locator cannot be resolved, the server returns a clear error message to help troubleshooting.
• Ensure the UI under test is accessible and not inside an iframe, as iframe handling is not supported by the current healing logic.
• For best results, provide descriptive descriptions in the fallback search (description parameter) to guide the text-based locator search.
• The server runs in an isolated container with no persistence of credentials; be mindful of any session or login flows in your tests.