weblab

weblab is an MCP server that drives real browsers, so AI agents can test and explore web apps. An agent opens named sessions (each a browser of its own pointing at an address), runs steps on them, and reads back what happened as text and screenshots.

Install

curl -fsSL https://raw.githubusercontent.com/dittofleet/weblab/main/install.sh | sh

This puts one binary at ~/.local/bin/weblab (set WEBLAB_INSTALL_DIR to change that). weblab runs on macOS, on Apple silicon and Intel, and drives a browser already on the machine: Google Chrome by default, or another Chromium browser.

To update, run weblab update. A running weblab looks for a newer release once a day, and says so in the reply to new when there is one.

Related MCP server: AI Web Tester

Register it with an MCP client

weblab speaks MCP over stdio, so the client starts it:

claude mcp add weblab -- weblab
codex mcp add weblab -- weblab

In a client's JSON config, the server entry is { "command": "weblab" }. Sessions last as long as that weblab process does: when the client goes, every session ends, and a server weblab started for them stops unless another weblab is still using it.

The tools

An example

new

{ "address": 5173, "start": "pnpm vite --port 5173", "path": "/settings" }

session main  at http://localhost:5173 (server started by weblab: pnpm vite --port 5173)
files $TMPDIR/weblab/shop-20261003-101600
started the server at http://localhost:5173 (pnpm vite --port 5173 in ~/code/shop); it stops when the last session on it ends
ok    1 goto (1840ms)
url   http://localhost:5173/settings
title Settings

console since the last reply:
  [console.log] app mounted (http://localhost:5173/src/main.tsx)

run

{
  "steps": [
    { "click": { "role": "button", "name": "Appearance" } },
    { "click": { "label": "Dark" } },
    { "expect": { "js": "document.documentElement.classList.contains('dark')" } },
    { "js": "localStorage.getItem('theme')" },
    { "shot": "appearance" }
  ]
}

ok    1 click (41ms)
ok    2 click (37ms)
ok    3 expect (12ms)
ok    4 js (3ms)
"dark"
ok    5 shot (95ms)
shot  $TMPDIR/weblab/shop-20261003-101600/shots/main-appearance.png

The screenshot also comes back as an image in the same reply. A step that fails is shown as FAIL 3 expect: ... with a screenshot of the page at that moment, and the session stays open for the next call.

What it can do

• Start the app with the command it is given when nothing answers at its address, share it among every session pointing there, and stop it when the last one ends. A server it didn't start is used as it is and left running. It never guesses how a project is run.

• Run any number of sessions at once: two users, copies of an app on several ports, Chrome, Edge, WebKit and Firefox side by side.

• Join a browser or Electron app that is already running, and leave it as it was found. Run code in an Electron app's main process too.

• Read the page as an accessibility tree with refs to act on, as text, or as HTML.

• Act and check: click, type, fill, drag, upload, and expect waits for text, elements, URLs, requests, console messages or any JavaScript.

• Shape what the page sees: fake API responses, colour scheme, viewport, locale, a saved sign-in, a slow network.

• See a React app the way React DevTools does: its components, where each one's code is, and what rendered and why. Change props, state and boundaries on the spot.

• Run JavaScript in the page, Playwright code against it, or raw Chrome DevTools Protocol commands, for anything the built-in steps don't cover.

• Keep screenshots, compare one with an earlier one, capture native menus from the real screen, record video and Playwright traces, and log the console and network.

Documentation

Development

bun install
bun test              # end-to-end tests, in the installed Chrome
bun run build         # dist/weblab, a single binary

src/main.ts is the entry point and src/mcp.ts defines the tools. Each step lives in src/steps/, grouped as Steps lists them. A release is a vX.Y.Z tag pushed on a commit on main, and nothing else: the release workflow builds the binaries, stamps the tag in as their version, and publishes them. No file in the repository holds the version, so there is nothing to bump.

The API is designed for how it reads now, not for what an earlier version took. Agents learn it from the tools' own descriptions and the docs each time they connect, so nothing depends on an old name the way a script would. When a clearer name or shape turns up, change it.