@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.
ANTHROPIC_API_KEY	One AI key required	Anthropic API key (for Claude models)
GOOGLE_API_KEY	One AI key required	Google AI API key (for Gemini models)
SHIPLIGHT_API_TOKEN	No	Shiplight cloud API token (enables cloud features)

At least one AI API key is needed for the test execution agent. The model is auto-detected from the key (ANTHROPIC_API_KEY → claude-haiku-4-5, GOOGLE_API_KEY → gemini-2.5-pro).

Pass environment variables through your MCP config:

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

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 is captured as a human-readable step, so sessions can be exported as .test.yaml files for fast, deterministic replay
• Sync to the cloud — Manage test cases on Shiplight's cloud platform for team-wide regression coverage (automatically enabled when SHIPLIGHT_API_TOKEN is set)
• Attach to existing Chrome tabs — Control your existing Chrome tabs via the Shiplight AI extension without recreating login state or complex setups

Links

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