# 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

```bash
npm install
npx playwright install chromium
```

## Usage

```bash
npm run build
npm start
```

Or for development with hot reload:

```bash
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:**

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

**Opencode:**

```json
{
  "$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