# MCP Server

<div class="view-markdown-wrapper">
<ViewMarkdown />
</div>

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`](https://www.npmjs.com/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](/local/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](/getting-started/quick-start#step-1-add-mcp-and-skills)**.

### Manual config

For agents that [`add-mcp`](https://www.npmjs.com/package/add-mcp) doesn't cover, paste this into your agent's MCP config file (location varies — check your agent's docs):

```json
{
  "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](/reference/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](https://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](/mcp/attach-to-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](/mcp/attach-to-browser) — drive a real Chrome window with all your logins and tabs intact
- [Browser Automation](/local/browser-automation) — workflows and use cases (verify UI, test with auth, mobile, extensions, debug failures)
- [Browser Options](/reference/browser-options) — full `new_session` `browser_options` reference
- [Choosing a Browser MCP](/reference/browser-mcp-tools) — Shiplight vs Playwright vs Chrome DevTools MCP