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 installnpm 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.