mcp-browser-automation

An MCP (Model Context Protocol) server for generic browser automation using Playwright. Exposes a headless Chromium instance as a set of callable tools so that MCP clients — such as AI coding assistants — can navigate pages, inspect elements, execute JavaScript, capture screenshots, and monitor console logs and network traffic.

Requirements

• Node.js 18+
• npm

Installation

npm install
npx playwright install chromium

Usage

npm run build
npm start

Or for development with hot reload:

npm run dev

The server listens on stdin/stdout using the MCP stdio transport. Configure your MCP client to launch it as a subprocess.

Claude Desktop:

{
  "mcpServers": {
    "browser-automation": {
      "command": "npx",
      "args": ["github:ritesh-jain/MCP-Browser-Automation"]
    }
  }
}

Opencode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp-browser-automation": {
      "type": "local",
      "enabled": true,
      "command": [
        "npx",
        "github:ritesh-jain/MCP-Browser-Automation"
      ]
    }
  }
}

Tools

Tool	Description
navigate	Navigate to a URL. Supports custom viewport and mobile emulation.
capture_screenshot	Take a full-page screenshot (saved to screenshots/).
get_console_logs	Retrieve browser console logs. Optionally clear after read.
get_network_traffic	Retrieve network requests and responses. Optionally clear after read.
execute_js	Execute arbitrary JavaScript in the page context.
interact	Click, type, fill, or select on a CSS selector.
inspect_element	Return tag name, id, class, inner text, outer HTML, and computed styles for an element.

Project Structure

src/
  types.ts           Shared type definitions
  McpServer.ts       MCP protocol layer — tool registration and dispatch
  BrowserManager.ts  Playwright orchestration — browser lifecycle and page interactions
index.ts             Entry point

How It Works

1. index.ts creates an McpBrowserServer and connects via StdioServerTransport.
2. An MCP client discovers tools via the ListTools request and calls them via CallToolRequest.
3. McpBrowserServer lazily initializes the browser on the first tool call and delegates to BrowserManager.
4. The browser stays open across calls, enabling multi-step interactions on the same page.

License

ISC