Where's Waldo Rick - Visual Regression

This MCP server provides agentic vision capabilities for visual regression testing, enabling you to capture platform screenshots, compare pixel-perfect changes, and receive annotated, zoomed analyses that highlight intended versus unintended differences across UI states.

How to use

Set up your client to communicate with the MCP server, declare your expected changes, capture baseline and current screenshots, and then compare them to reveal precise visual differences. You will interact with the MCP through a client that issues the visual workflow commands, leveraging the agentic vision analysis to annotate changes and guide investigation.

How to install

Prerequisites you need before installing this server are Python 3.10 or newer and a Gemini API key.

# Install via uvx from GitHub
uvx --from git+https://github.com/bretbouchard/gemini-vision-mcp wheres_waldo.server

# Or install locally in editable mode
pip install -e .

Configuration and initial setup

Configure your Claude Code MCP to include the Where’s Waldo Rick server. Provide the runtime command, the repository path, and your Gemini API key in the environment.

{
  "mcpServers": {
    "wheres-waldo-rick": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/bretbouchard/gemini-vision-mcp", "wheres_waldo.server"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Usage pattern with the MCP client

Enqueue a prepare step to declare the expected changes, capture a baseline screenshot, perform development, capture the current state, and then run a comparison to visualize all changes. The following sequence demonstrates the typical workflow.

Notes on security and keys

Keep your Gemini API key confidential and scoped to the necessary rate limits. Do not expose the key in public configurations or version control.

Additional notes

This server is designed to work with multi-platform screenshots (macOS, iOS Simulator, Web) and supports configurability for pixel thresholds and iterative analysis.

Available tools

visual_capture

Capture a screenshot for a given phase and platform and store it for visual regression testing.

visual_prepare

Declare the baseline with the expected changes before development begins.

visual_compare

Compare two screenshots with pixel-level precision and agentic vision analysis to surface changes.

visual_cleanup

Remove old screenshots and prune cached data to keep storage tidy.