MCP Server

View as Markdown

The Shiplight MCP server gives your AI coding agent the ability to drive a real browser — launch sessions, inspect pages, perform actions, capture evidence, and read console and network logs. All browser actions are deterministic, so no LLM API keys are needed by the server itself. Your coding agent (Claude Code, Cursor, VS Code, Codex, etc.) handles the reasoning; Shiplight executes.

Package: @shiplightai/mcp. Always run latest via npx -y @shiplightai/mcp@latest — no manual update step.

How It Works

Your agent works through a simple loop:

launch → inspect → interact → verify → close

1. Launch — new_session opens a Chromium browser. Choose fresh, a persistent Chrome profile, or attach to an already-open browser. Emulation, extensions, and recording are configurable per session.
2. Inspect — inspect_page returns a DOM tree plus a Set-of-Mark screenshot with element indices the agent can reference.
3. Interact — act performs actions (click, type, scroll, upload, keyboard, tab switching) using element indices from inspect_page.
4. Verify — the agent re-inspects the page, or pulls get_browser_console_logs / get_browser_network_logs to confirm the change.
5. Close — close_session returns video and Playwright trace paths if recording was enabled.

For end-to-end workflows that use this loop, see Browser Automation.

Install

For per-agent copy-paste install commands (Claude Code, Cursor, VS Code, Codex, Gemini CLI, Copilot CLI, Claude Desktop, Zed, OpenCode, Antigravity), see Quick Start → Step 1.

Manual config

For agents that add-mcp doesn't cover, paste this into your agent's MCP config file (location varies — check your agent's docs):

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

Tool Reference

Session Management

Tool	Description
new_session	Launch a browser with optional emulation and extensions
close_session	Close a session (returns video/trace paths if recording)
close_all	Close all sessions
get_session_state	Get current URL and session type
save_storage_state	Save cookies/localStorage for fast session restore
attach_to_browser	Connect to an existing browser via relay or CDP

new_session accepts a rich set of browser_options — viewport, mobile emulation, color scheme, locale, geolocation, proxy, persistent profile, and more. See Browser Options for the full list.

Page Inspection

Tool	Description
navigate	Navigate to a URL
get_page_info	Get current page URL and title (lightweight, no screenshot)
inspect_page	DOM tree + Set-of-Mark screenshot (element indices for the act tool)
get_locators	Extract Playwright locator/xpath for elements

Actions

Tool	Description
act	Execute browser actions (click, type, scroll, etc.) using element indices from inspect_page

Debugging

Tool	Description
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

Reporting

Tool	Description
generate_html_report	Generate a self-contained HTML report with screenshots, video, and checklist
upload_html_report	Upload an HTML report to Shiplight Cloud for sharing

Configuration

All configuration is done through environment variables. The MCP server discovers them in this order:

1. Your project's .env file (auto-discovered on startup)
2. The env block in your MCP server config
3. Shell exports

Environment Variables

Variable	Required	Description
SHIPLIGHT_API_TOKEN	For cloud features	Shiplight API token — enables cloud sync tools. Get your token from app.shiplight.ai/settings/api-tokens.
SHIPLIGHT_RELAY_PORT	For relay attach	Port for the Chrome extension relay server. Required when using attach_to_browser via the Shiplight Chrome extension. See Attach to Existing Browser.
PWDEBUG	No	Playwright debug mode. The install commands set PWDEBUG=console so the agent sees browser console output inline.

Next Steps

• Attach to Existing Browser — drive a real Chrome window with all your logins and tabs intact
• Browser Automation — workflows and use cases (verify UI, test with auth, mobile, extensions, debug failures)
• Browser Options — full new_session browser_options reference
• Choosing a Browser MCP — Shiplight vs Playwright vs Chrome DevTools MCP