@shiplightai/mcp-cloud

Shiplight MCP Server

AI-powered web testing through the Model Context Protocol.

Shiplight lets AI coding agents — Claude Code, Cursor, Windsurf, and any MCP-compatible tool — browse, interact with, and test web applications. Write tests in natural language, run them in the cloud, and get detailed results — all from your IDE.

Why Shiplight

Other browser MCP servers (like Playwright MCP) give your coding agent basic browser control. Shiplight goes further:

Capability	Playwright MCP	Shiplight
Browser automation (click, type, scroll)	Yes	Yes
AI-powered assertions (verify)	No	Yes *
AI data extraction (ai_extract)	No	Yes *
Natural language test flows (YAML DSL)	No	Yes
Conditional logic (IF/ELSE)	No	Yes *
Loops (WHILE)	No	Yes *
Cloud test execution & results	No	Yes
Test case management (CRUD, folders)	No	Yes
Enrichment workflow (DRAFT to ACTION)	No	Yes

* Uses the web agent (secondary LLM)

Shiplight also uses set-of-mark technology for better identifying interactive elements and handles cross-frame elements transparently — no manual iframe switching needed.

Shiplight is not just a browser driver — it's a complete test automation platform accessible through MCP.

Quick Start

Install

npm install -g @shiplightai/mcp-cloud

Claude Code

claude mcp add shiplight -- shiplight-mcp-cloud \
  -e GOOGLE_API_KEY=your-google-api-key \
  -e WEB_AGENT_MODEL=gemini-2.5-pro \
  -e PWDEBUG=console

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "shiplight": {
      "command": "shiplight-mcp-cloud",
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key",
        "WEB_AGENT_MODEL": "gemini-2.5-pro",
        "PWDEBUG": "console"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "shiplight": {
      "command": "shiplight-mcp-cloud",
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key",
        "WEB_AGENT_MODEL": "gemini-2.5-pro",
        "PWDEBUG": "console"
      }
    }
  }
}

The MCP server runs a web agent — a secondary LLM that looks at the browser page and decides how to act. This agent powers:

• AI-powered actions: verify, ai_extract, ai_wait_until
• Natural language test steps: DRAFT statements and VERIFY assertions in test flows
• Conditional evaluation: IF/ELSE and WHILE conditions written in natural language

Browser actions like click, input_text, scroll etc. do not require the web agent — they execute deterministically.

You can use either a Google or Anthropic API key. Set WEB_AGENT_MODEL to match your provider:

Provider	API Key	Supported Models
Google	GOOGLE_API_KEY	gemini-2.5-pro, gemini-3-pro-preview
Anthropic	ANTHROPIC_API_KEY	claude-haiku-4-5, claude-sonnet-4-5, claude-opus-4-5

To unlock cloud test management, add your Shiplight API token:

{
  "env": {
    "GOOGLE_API_KEY": "your-google-api-key",
    "WEB_AGENT_MODEL": "gemini-2.5-pro",
    "PWDEBUG": "console",
    "API_TOKEN": "your-shiplight-api-token-here"
  }
}

Free: Browser Automation & UI Verification

No Shiplight account needed. Launch a browser, interact with any web app, and verify UI state — all driven by your AI coding agent.

Your coding agent can verify UI features by:

• Opening a browser and navigating to your app
• Inspecting page state via screenshots and DOM structure
• Interacting with elements: click, type, select, scroll, upload files
• Asserting UI state with natural language (e.g., "the login form should be visible")
• Capturing console errors and network requests

Example — prompt your coding agent:

Add a "Forgot Password?" link below the login form. After implementing,
Use Shiplight to verify your implementation in the browser.

Free Tools

Tool	Description
new_session	Create a browser session with optional device emulation and auto-login
close_session	Close a browser session
close_all	Close all browser sessions
get_session_state	Get current URL and session info
save_storage_state	Save cookies/localStorage for fast session restore
navigate	Navigate to a URL
get_page_info	Get current page URL and title
inspect_page	Screenshot + DOM with interactive element indices
act	Perform browser actions (click, type, scroll, verify, etc.)
get_locator	Extract Playwright locator/xpath for an element
update_variables	Set session variables for use in actions
clear_execution_history	Reset session action history
get_browser_console_logs	Get browser console output with filtering
get_browser_network_logs	Get network requests with status filtering
clear_logs	Clear console and network logs
get_local_artifact	Retrieve a saved screenshot or DOM snapshot

Browser Actions

The act tool supports the following actions for interacting with the page:

Action	Description
click	Click an element
double_click	Double-click an element
right_click	Right-click an element
hover	Hover over an element
input_text	Type text into an input field
clear_input	Clear an input field
press	Press a key or key combination (e.g., Enter, Control+A)
send_keys_on_element	Send keys to a specific element
select_dropdown_option	Select from a dropdown by value or label
get_dropdown_options	List all options in a dropdown
set_date_for_native_date_picker	Set date on a native date picker input
scroll	Scroll up or down by number of pages
scroll_to_text	Scroll until specific text is visible
scroll_on_element	Scroll within a specific scrollable element
go_to_url	Navigate to a URL
go_back	Go back in browser history
reload_page	Reload the current page
switch_tab	Switch to a different browser tab
close_tab	Close a browser tab
upload_file	Upload a file via file input

Utility Actions

Action	Description
wait	Wait for a specified duration
wait_for_page_ready	Wait until the page finishes loading
wait_for_download_complete	Wait for a file download to complete
save_variable	Save a value to a session variable
generate_2fa_code	Generate a TOTP 2FA code from a secret key

AI-Powered Actions *

These actions use the AI model specified by WEB_AGENT_MODEL to reason about the page:

Action	Description
verify *	Assert page state with a natural language statement
ai_extract *	Extract data from the page into a variable
ai_wait_until *	Wait until an AI-evaluated condition is true

Writing Tests in Natural Language

Shiplight tests are written in YAML using natural language. Start with plain English, then optionally enrich with locators for speed.

No lock-in: Test flows are exported as pure Playwright + Shiplight Agent SDK code for execution. The YAML DSL is an authoring format — what actually runs is standard Playwright with an AI agent layer on top. You can eject at any time.

Basic Test (all natural language)

goal: Verify user can create a new project
url: https://app.example.com/projects
statements:
  - Click the "New Project" button
  - Enter "My Test Project" in the project name field
  - Select "Public" from the visibility dropdown
  - Click "Create"
  - "VERIFY: Project page shows title 'My Test Project'"
teardown:
  - Delete the created project

Every line is a plain English instruction. The AI resolves each one at runtime by looking at the page and performing the right action.

Enriched Test (with locator)

After exploring the UI with the free browser tools, you can add locators for deterministic, fast replay:

goal: Verify user can create a new project
url: https://app.example.com/projects
statements:
  - STEP: Create project
    statements:
      - description: Click the New Project button
        action_entity:
          action_data:
            action_name: click
          locator: "getByRole('button', { name: 'New Project' })"
      - description: Enter project name
        action_entity:
          action_data:
            action_name: input_text
            kwargs:
              text: "My Test Project"
          locator: "getByRole('textbox', { name: 'Project name' })"
      - description: Click Create
        action_entity:
          action_data:
            action_name: click
          locator: "getByRole('button', { name: 'Create' })"
  - "VERIFY: Project page shows title 'My Test Project'"
teardown:
  - Delete the created project

Natural language statements (~10-15s each): AI reads the page and figures out what to do. Action statements with locator (~1s each): Replay deterministically without AI. VERIFY statements: Always use AI — just provide a clear assertion in plain English.

Locators are a cache, not a hard dependency. When the UI changes and a locator becomes stale, Shiplight's agentic layer auto-heals by falling back to the natural language description. When running on the Shiplight cloud, the platform automatically updates the cached locator after a successful self-heal — so future runs replay at full speed without manual maintenance.

Statement Types

Type	Syntax	Description
Natural language *	- Click the login button	AI resolves at runtime
Action with locator	- description: ... + action_entity: ...	Deterministic replay
Verify *	- "VERIFY: page shows welcome message"	AI-powered assertion
Step group	- STEP: Login + statements: [...]	Group related actions
Conditional *	- IF: cookie banner is visible + THEN: [...]	Conditional execution
Loop *	- WHILE: more items to load + DO: [...]	Repeat until condition

Conditional Logic & Loops

Shiplight tests support branching and looping — handle real-world UI variability without separate test cases.

IF / ELSE — handle optional UI elements:

statements:
  - IF: cookie consent dialog is visible
    THEN:
      - Click "Accept All"
  - IF: user is logged in
    THEN:
      - Click the logout button
    ELSE:
      - Click the login button
      - Enter credentials and submit

WHILE — repeat until a condition is met:

statements:
  - WHILE: "Load More" button is visible
    DO:
      - Click the "Load More" button
      - Wait for new items to appear
  - "VERIFY: all items are loaded"

Conditions are evaluated by AI at runtime using the current page state. You can also use JavaScript conditions with the js: prefix:

  - IF: "js: document.querySelectorAll('.item').length < 10"
    THEN:
      - Click "Load More"

The Enrichment Workflow

• Draft — Write tests in plain English
• Explore — Use inspect_page and act to walk through the UI
• Collect — Use get_locator to capture element locators
• Enrich — Replace natural language with action_entity + locator
• Result — Tests run 10x faster with deterministic replay

You can mix natural language and enriched statements in the same test. Start with all natural language, then selectively enrich the most-used flows.

Cloud: Test Case Management & Execution

Requires a Shiplight API token.

Store test cases in the cloud, trigger runs, and analyze results with full runner logs, screenshots, and trace files.

What you can do:

• Create and update test cases from YAML flows
• Trigger cloud test runs across environments
• Get detailed results: step-by-step status, screenshots, runner logs
• Manage test infrastructure: environments, test accounts, folders

Example conversation:

You: Create a test case from my login-test.yaml and run it on staging

Claude: [reads YAML, creates test case, triggers run, polls for results]
Test case #502 created. Cloud run completed in 1m 23s — all 8 steps passed.

Cloud Tools

Tool	Description
create_test_case	Create a test case from a YAML flow or JSON object
update_test_case	Update an existing test case flow
get_test_case	Get test case details (supports YAML output)
run_test_case	Trigger a cloud test run
list_test_runs	List test runs with filtering
get_test_run_details	Get run status and test case results
get_test_case_result	Get detailed result with runner logs (stdout/stderr)
get_test_case_result_steps	Get step-by-step execution details
get_step_artifacts	Download screenshots and artifacts for a step
list_environments	List testing environments
list_test_accounts	List test accounts for an environment
get_test_account	Get test account details
create_test_account	Create a test account with login config
list_folders	List test case folders
create_folder	Create a folder for organizing test cases
get_folder	Get folder details with full path

Workflow Examples

Shiplight MCP fits naturally into AI-driven development. Your coding agent can verify UI changes in a live browser as you code, and automatically create enriched test cases from the session — no context switching needed. See the workflow guide for detailed examples, including how to set up a Claude Code custom agent for fully autonomous test creation.

Coming Soon

• Coordinate-based actions — click_by_coordinates, drag_drop for pixel-precise interactions (canvas, maps, visual editors)

Configuration

Variable	Required	Description	Default
GOOGLE_API_KEY	One of these	Google AI API key	—
ANTHROPIC_API_KEY	required	Anthropic API key	—
WEB_AGENT_MODEL	Yes	AI model for browser automation	—
PWDEBUG	No	Set to console to enable Playwright debug logging	—
API_TOKEN	For cloud features	Shiplight API token	—
API_BASE_URL	No	Shiplight API URL	https://api.shiplight.ai

Resources & Prompts

The server exposes MCP resources with schema documentation:

Resource	Description
shiplight://schemas/testflow-v1.2.0	TestFlow YAML/JSON format, statement types, examples
shiplight://schemas/action-entity	Browser action parameters for the act tool

Getting an API Token

To unlock cloud test management:

• Visit shiplight.ai to create an account
• Generate an API token from your account settings
• Set API_TOKEN in your MCP server configuration

License

MIT