@shiplightai/mcp

@shiplightai/mcp

UI automation MCP for agentic development workflows. Lets AI coding agents (Claude Code, Cursor, Windsurf, etc.) verify the UI changes they make — closing the build-verify loop automatically. Every interaction is captured as a human-readable step, producing rerunnable regression tests.

Quick Start

Claude Code

claude mcp add shiplight -e PWDEBUG=console -- npx -y @shiplightai/mcp@latest

Cursor / Windsurf / Other MCP Clients

Add to your MCP config (e.g., .cursor/mcp.json):

{
  "mcpServers": {
    "shiplight": {
      "command": "npx",
      "args": ["-y", "@shiplightai/mcp@latest"]
    }
  }
}

Environment Variables

Variable	Required	Description
PWDEBUG	Yes	Must be set to console. Enables Playwright semantic locator generation (e.g., getByRole, getByTestId) for action entities. Without this, only XPath locators are available.

No AI API key is required. Every tool this server exposes is deterministic: actions are driven by the element indices returned from inspect_page, not by a model. Your coding agent supplies the intelligence; this server supplies the browser.

Pass environment variables through your MCP config:

{
  "mcpServers": {
    "shiplight": {
      "command": "npx",
      "args": ["-y", "@shiplightai/mcp@latest"],
      "env": {
        "PWDEBUG": "console"
      }
    }
  }
}

The server resolves environment variables in this order:

• Variables passed explicitly by your MCP client config
• Inherited host environment variables
• A .env file in the current working directory where the MCP server starts

Existing environment variables are never overridden by .env, so project-local .env values act as a fallback.

What It Does

Once connected, your AI coding agent can:

• Verify its own UI changes — Open pages, interact with elements, and assert visual conditions using AI ("Verify the success message is displayed")
• Debug UI issues — Inspect console errors and network failures directly from the browser session
• Generate regression tests — Every action returns replay-ready locator data (locator/xpath/frame_path) you embed into .test.yaml files authored with the shiplightai CLI, for fast, deterministic replay
• Attach to existing Chrome tabs — Control your existing Chrome tabs via the Shiplight AI extension without recreating login state or complex setups

Links

• Shiplight — home page
• shiplightai npm package — Playwright plugin for running .test.yaml files locally