mare-browser-mcp

A lean, LLM-first browser automation MCP server. Gives Claude (or any MCP client) a real Chromium browser to navigate, interact with, and debug web apps — without the overhead of raw Playwright APIs.

Built with Playwright + MCP SDK. One server = one browser session = one LLM.

Free to use. If it saves you time, buy me a coffee ☕

Quick Start (npx)

Prerequisites: Node.js 18+

npx mare-browser-mcp

That's it. First run will install Playwright's Chromium automatically if needed.

Install from source

git clone https://github.com/emadklenka/mare_browser_mcp
cd mare-browser-mcp
pnpm install
npx playwright install chromium

Register with Claude Code

pnpm run setup

That's it. The script detects the correct path automatically and registers the MCP with Claude Code. Restart Claude Code and the browser tools are ready.

Manual config — add to ~/.claude.json under mcpServers:

{
  "mcpServers": {
    "mare-browser": {
      "command": "npx",
      "args": ["mare-browser-mcp"],
      "env": { "HEADLESS": "false" }
    }
  }
}

Or if installed from source, use the absolute path:

{
  "mcpServers": {
    "mare-browser": {
      "command": "node",
      "args": ["/absolute/path/to/mare-browser-mcp/src/index.js"],
      "env": { "HEADLESS": "false" }
    }
  }
}

Register with OpenCode

Add this to ~/.config/opencode/opencode.json (global) or opencode.json (project root):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mare_browser_mcp": {
      "type": "local",
      "command": ["npx", "mare-browser-mcp"]
    }
  }
}

Or if installed from source, use the absolute path:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mare_browser_mcp": {
      "type": "local",
      "command": [
        "node",
        "/absolute/path/to/mare-browser-mcp/src/index.js"
      ]
    }
  }
}

Tools

browser_navigate(url, clear_logs?)

Navigate to a URL. Pass clear_logs: true when starting a new task to wipe stale console/network/dialog history.

browser_act(commands[])

Run a sequence of actions in one call. Supported actions:

| action | required params | optional params | what it does | |---|---|---|---| | click | selector | button (left/right/middle) | Click an element. Use button: "right" for context menus | | hover | selector | | Hover over an element — triggers tooltips, dropdown menus, hover states | | drag | selector | target or offsetX/offsetY | Drag an element to another element (target) or by pixel offset (for resizing, sliders) | | clicklink | text | | Click a link/button by its visible text | | fill | selector, value | | Type into an input (clears first) | | select | selector, value | | Select a dropdown option | | keypress | key | | Press a key (e.g. Enter, Tab, Escape) | | waitfor | selector | timeout | Wait until element appears | | scrollto | selector | | Scroll element into view | | wait | ms | | Pause for N milliseconds | | clearconsole | — | | Clear console log buffer |

browser_debug()

Start here when something goes wrong. Returns in one call:

• Current URL and page title
• Console logs (filterable by type: error, warning, log, pageerror)
• Network requests with: method, URL, query params, request body, request headers (auth masked), status code, response body (JSON), and duration_ms timing
• Dialog history (alert/confirm/prompt — auto-accepted, text captured)

Filter with url_filter, method_filter, console_types, or last_n.

browser_query(selector, all?, fields?, visible_only?, limit?, count_only?)

Read the DOM without a screenshot. Query any element by CSS selector.

| param | what it does | |---|---| | all | Return all matching elements (default: first only) | | fields | Pick fields: text, value, visible, disabled, className, href, innerHTML | | visible_only | Filter to visible elements only — recommended for broad selectors | | limit | Cap the number of results (e.g. 10) to prevent huge payloads | | count_only | Just return the count — fast way to check "how many rows?" without fetching data |

browser_eval(code)

Escape hatch for anything the other tools don't cover:

• Read computed styles: getComputedStyle(el).backgroundColor
• Append text to inputs without clearing
• Type character-by-character for autocomplete
• Drag-and-drop via manual DOM events
• Call fetch() to hit APIs directly
• Read JS app state (window.__store__, etc.)
• Check CSS visibility (display, opacity, visibility)

browser_scroll(direction?, pixels?, selector?, container?)

Three modes:

• Page scroll: direction: "down", pixels: 500
• Scroll into view: selector: ".my-element"
• Scroll within a container: container: ".ag-body-viewport", direction: "down", pixels: 300 — for scrollable divs, grid viewports, chat panels

browser_wait_for_network(url_pattern?, method?, timeout?)

Wait for a specific network response after triggering an action — smarter than guessing with wait.

browser_screenshot()

Returns a PNG screenshot. Use as a last resort — prefer browser_debug and browser_query first.

browser_upload(selector, files[])

Upload files to a file input element.

browser_restart(url?)

Kill the browser and start fresh. Clears all logs. Optionally navigate to a URL after restart.

Example workflow

1. browser_navigate("https://myapp.com", clear_logs: true)
2. browser_act([
     { action: "fill", selector: "#email", value: "[email protected]" },
     { action: "fill", selector: "#password", value: "secret" },
     { action: "click", selector: "button[type=submit]" }
   ])
3. browser_wait_for_network({ url_pattern: "/api/session", method: "POST" })
4. browser_debug({ console_types: ["error"] })   <- check for login errors
5. browser_query(".dashboard-title")              <- confirm we're logged in

Hover + tooltip example

1. browser_act([{ action: "hover", selector: ".info-icon" }])
2. browser_query(".tooltip", { fields: ["text", "visible"] })

Drag-and-drop example

// Reorder columns
browser_act([{ action: "drag", selector: ".col-name", target: ".col-age" }])

// Resize a column by 100px
browser_act([{ action: "drag", selector: ".resize-handle", offsetX: 100, offsetY: 0 }])

Right-click context menu

1. browser_act([{ action: "click", selector: ".grid-row", button: "right" }])
2. browser_query(".context-menu-item", { all: true, fields: ["text"] })

Scroll inside a container

browser_scroll({ container: ".ag-body-viewport", direction: "down", pixels: 500 })

Count elements quickly

browser_query({ selector: ".ag-row", count_only: true })
// -> { selector: ".ag-row", count: 47 }

Environment

| Variable | Default | Description | |---|---|---| | HEADLESS | false | Run browser headless (true) or visible (false) | | REAL_CHROME | false | Use your installed Chrome instead of Playwright's Chromium | | CHROME_PROFILE | Default | Chrome profile name (when REAL_CHROME=true) |

The browser launches lazily — it won't open until the first tool call.

License

MIT — free to use, modify, and distribute.

If this project helps you, buy me a coffee ☕