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

1. npm install
2. 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.