Browser Automation MCP Server

This TypeScript project spins up a Model Context Protocol (MCP) server that exposes three tooling primitives tailored for automation: browser-driven flows, API health checks, and visual comparisons. It listens on STDIO, so any MCP-aware agent (Claude, Cursor, LangChain, etc.) can start the Node process and negotiate tools/list + tools/call automatically.

Setup

npm install
npm run build

Running the server

Execute npm run start (or node build/server.js directly). The server already binds to STDIO, so configure your MCP client to launch the same command and keep the subprocess running while the agent is issuing tool requests.

Tool catalogue

Tool	Description	Inputs	Outputs
`run-browser-automation`	Navigates a Chromium tab, runs scripted actions (click/fill/assert), and optionally returns a final screenshot.	`url` (required), `actions` array (navigate/click/fill/type/press/assert/wait), viewport/device scale, `finalScreenshot` flag.	`steps` array, summary, optional screenshot (`data:image/png;base64,...`).
`run-api-check`	Hits any HTTP endpoint to verify status and capture response snippets.	`url` (required), HTTP `method`, `headers`, `body`, expected status.	HTTP `status`, comparison to `expectStatus`, response snippet, response headers.
`compare-page-screenshots`	Captures two pages at the same viewport and runs pixelmatch to flag visual regressions.	`baselineUrl`, `targetUrl`, optional `viewport`/`threshold`.	Pixel mismatch ratio, diff image (base64 PNG), baseline dimensions.

Example tool call payloads

Browser automation

{
  "url": "https://example.com/login",
  "actions": [
    {"type": "fill", "selector": "#username", "value": "test"},
    {"type": "fill", "selector": "#password", "value": "secret"},
    {"type": "click", "selector": "#submit"},
    {"type": "waitForSelector", "selector": "#welcome"}
  ],
  "finalScreenshot": true
}

Image comparison

{
  "baselineUrl": "https://example.com/home?baseline=1",
  "targetUrl": "https://example.com/home?baseline=2",
  "threshold": 0.04
}

Debugging & exploration

Use the MCP Inspector to validate the server before wiring it to a client. Run npx @modelcontextprotocol/inspector node build/server.js, open the Inspector UI, and review the tools tab, send sample arguments, and inspect logs. The Inspector also proxies your server so you can replicate production-style connections locally.

Browser Automation MCP Server