mcp-browser-automation

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