web-ui-tester

An MCP server that lets an AI drive and inspect real web pages quickly, over browser sessions that stay alive between tool calls.

Two things make it fast. Pages are exposed as an accessibility tree with element refs rather than screenshots or raw HTML, so the model can find and click things without burning context on markup or waiting on vision. And sessions persist — cookies, page state, and history survive across calls, so a long interaction is a series of cheap steps instead of repeated cold starts.

It also carries DevTools-grade diagnostics — console, network with response bodies, JS evaluation, computed styles — so the AI can work out why something is broken, not just that it is.

Quick start

claude mcp add web-ui-tester -- npx -y web-ui-tester

With a key for the built-in agent (see run_task):

claude mcp add web-ui-tester \
  -e GOOGLE_GENERATIVE_AI_API_KEY=your-key \
  -- npx -y web-ui-tester

Or in any MCP client's config file:

{
  "mcpServers": {
    "web-ui-tester": {
      "command": "npx",
      "args": ["-y", "web-ui-tester"],
      "env": { "GOOGLE_GENERATIVE_AI_API_KEY": "your-key" }
    }
  }
}

Chromium comes from Playwright. If it isn't installed yet:

npx playwright install chromium

How a session works

browser_start          → sessionId, kept alive across calls
browser_navigate       → page state + snapshot with [ref=eN] handles
browser_click ref=e12  → act on what the snapshot showed you
browser_snapshot       → fresh refs after the page changes
browser_close          → done (or let it idle out after 30 minutes)

Everything after browser_start takes that sessionId. The snapshot is the thing to get used to:

- generic [ref=e1]:
  - heading "Signup" [level=1] [ref=e2]
  - textbox "Name" [ref=e5]:
    - /placeholder: Your name
  - combobox "Plan" [ref=e7]
  - button "Create account" [ref=e10]
  - link "Go to second page" [ref=e12] [cursor=pointer]:
    - /url: /second.html

Those refs go straight into browser_click, browser_type, and the rest. They belong to the page state that produced them: after navigating or a DOM change, snapshot again. When a tool says a ref is no longer valid, re-snapshot rather than retry — the message says so explicitly.

Element-addressing tools also accept css, or role + name, when you already know the selector and would rather skip the snapshot.

Tools

Session — browser_start (options: userAgent, viewportWidth, viewportHeight, headless, baseUrl, url, model), browser_list, browser_close.

Interaction — browser_navigate, browser_click, browser_type, browser_press_key, browser_hover, browser_select_option, browser_scroll, browser_wait_for, browser_go_back, browser_handle_dialog.

Actions report what they caused: navigation, new console errors, request counts, and any dialog that appeared come back with the result, so a click that quietly broke something doesn't look like a success.

Dialogs need one note. An alert/confirm/prompt blocks the page until it's answered, so the action that opened it can't also answer it — an unanswered dialog is dismissed automatically rather than stalling the click, and the result says so. To accept one, or to fill in a prompt, call browser_handle_dialog before the action that triggers it and the answer is armed for the next dialog.

Inspection — browser_snapshot (scopeable by element, depth-limited, interactiveOnly, offset-paged), browser_query (find by role/name, text, or CSS — returns refs and state), browser_read_text (rendered text of the page or one subtree), browser_screenshot (available, but the tree is usually the better tool).

Diagnostics — browser_console (messages plus uncaught errors with stacks), browser_network (statuses, sizes, timings), browser_request_detail (headers, timing breakdown, request and response bodies), browser_evaluate (run JS in the page), browser_inspect_element (computed styles, box model, form state).

Every result is capped to a character budget, and the large ones (browser_snapshot, browser_read_text, bodies) page with offset instead of truncating silently.

The built-in agent

run_task hands a session to a fast model that drives the browser itself and reports back:

run_task(sessionId, "Log in as demo@example.com / hunter2 and check the
                     dashboard loads without errors")

Reporting is the point. It returns a structured verdict, not just prose:

status: success
model: google:gemini-flash-lite-latest

Logged in and opened the dashboard. The revenue widget rendered empty.

findings (3):
  [error] Request failed: GET 500 [observed by the harness]
      where: https://app.example.com/api/revenue
      evidence: HTTP 500
  [error] Console exception on the page [observed by the harness]
      where: app.js:214:9
      evidence: TypeError: Cannot read properties of undefined (reading 'total')
  [warning] The revenue widget shows no empty state, just blank space
      where: #revenue-card
      evidence: card is present but contains no text

Findings come from two places, and the distinction matters. The agent calls report_finding as it goes — so a run that hits its step limit still returns everything it found up to that point. Separately, the harness records every console error, failed request, and dialog during the run and reports those whether or not the agent mentions them, marked [observed by the harness]. A model that misses a 500 or forgets to mention an exception can't hide it.

The same report is returned as structuredContent against a declared output schema, so a calling AI can branch on findings[].severity rather than parse text. A task can succeed and still have findings; success reflects whether the task was accomplished, not whether the page was clean.

This is the one part that needs an API key. It defaults to Gemini Flash Lite for latency; Anthropic works too:

Set WUT_MODEL to pick (anthropic, or google:gemini-flash-latest, or any provider:modelId). A session can override it via browser_start's model, and a single call via run_task's model. Every other tool works without a key.

HTTP mode

web-ui-tester --port 7399
claude mcp add --transport http web-ui-tester http://127.0.0.1:7399/mcp

In this mode the browser sessions live in the long-running server rather than in a client-owned process, so they survive client restarts and reconnects — reconnect, pass the same sessionId, and the page is still there. GET /health reports session and connection counts.

It binds to 127.0.0.1 by default, where DNS-rebinding protection is enabled. --host widens that, and the server warns when you do: there is no authentication, and anyone who can reach the port can drive a browser and run JavaScript through it. Put it behind a proxy or firewall.

Configuration

CLI flags: --port, --host, --headless / --no-headless, --idle-timeout, --version, --help.

If Playwright's expected Chromium revision isn't installed but another one is, the server finds and uses it rather than failing — handy in prebuilt containers. WUT_EXECUTABLE_PATH overrides the search entirely.

Development

npm install
npm run build
npm test          # agent loop (mocked model) + full end-to-end suite
npm run typecheck

npm test runs the agent loop against a scripted mock model, then drives the built server as a real MCP client over both transports against a local fixture app — covering refs, stale-ref handling, diagnostics, session persistence across reconnects, and idle reaping. npm run test:agent:live additionally exercises run_task against a real provider, and skips itself when no key is set.

License

MIT