Browser MCP

Browser MCP is an Electron-based Model Context Protocol server that gives MCP clients control over a real local browser window. It exposes tools for starting browser sessions, reading page context, clicking, typing, dragging, scrolling, taking screenshots, inspecting console logs, and reviewing network requests.

The package is published on NPM as @cypherpotato/browser-mcp.

Contents

• How it works

• Requirements

• Installation

• MCP client configuration

• Running the HTTP sentinel

• CLI reference

• Tools

• Environment variables

• Development

• Troubleshooting

Related MCP server: Tabrix

How it works

Browser MCP has two runtime layers:

1. A Node entrypoint named browser-mcp-electron.

2. An Electron browser host that opens and controls real browser windows.

By default, MCP clients should start the package with --mcp. That command starts or reuses a local HTTP sentinel, then proxies MCP messages over stdin/stdout for the client.

flowchart LR
  Client["MCP client"] --> Stdio["browser-mcp-electron --mcp"]
  Stdio --> Sentinel["Local HTTP sentinel"]
  Sentinel --> Electron["Electron browser host"]
  Electron --> Page["Live browser session"]

The sentinel stores its current local endpoint in the operating system temp directory under browser-mcp-electron-sessions/sentinel.json. The server only listens on 127.0.0.1.

Requirements

• Node.js 18 or newer.

• npm or another Node package manager.

• A desktop session capable of running Electron.

• Linux only: the usual Electron runtime libraries for your distribution.

Installation

Install globally if your MCP client will call the binary directly:

npm install -g @cypherpotato/browser-mcp

Or run it without a global install:

npx @cypherpotato/browser-mcp --help

To verify the binary:

browser-mcp-electron --help

MCP client configuration

Use the stdio bridge mode for normal MCP client integration:

{
  "mcpServers": {
    "browser": {
      "command": "browser-mcp-electron",
      "args": ["--mcp"]
    }
  }
}

With npx:

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "@cypherpotato/browser-mcp", "--mcp"]
    }
  }
}

Optional startup URL and profile directory:

{
  "mcpServers": {
    "browser": {
      "command": "browser-mcp-electron",
      "args": [
        "--mcp",
        "--url",
        "https://example.com",
        "--data-dir",
        "~/.browser-mcp"
      ]
    }
  }
}

Running the HTTP sentinel

For normal MCP client usage, configure the client to run browser-mcp-electron --mcp. That command starts the HTTP sentinel automatically when needed and reuses a healthy sentinel when one already exists.

Run the HTTP sentinel manually only when you want to manage the browser host separately from an MCP stdio client.

Start it in the foreground:

browser-mcp-electron --mcp-http --url https://example.com --data-dir ~/.browser-mcp

Start it in the background and return after it is healthy:

browser-mcp-electron --mcp-http-background --url https://example.com --data-dir ~/.browser-mcp

Pin the local sentinel port:

browser-mcp-electron --mcp-http-background --sentinel-port 55332

When --mcp runs later, it reuses a healthy sentinel when one exists. If no healthy sentinel exists, it starts one automatically.

CLI reference

browser-mcp-electron [--mcp] [--url <url>] [--data-dir <path>]
browser-mcp-electron --mcp-http [--url <url>] [--data-dir <path>]
browser-mcp-electron --mcp-http-background [--url <url>] [--data-dir <path>]
browser-mcp-electron --mcp-stdio [--url <url>] [--data-dir <path>]

Tools

browser_toggle_session

Starts or stops a real Electron browser session.

Start a session:

{
  "action": "start",
  "start_url": "https://example.com"
}

Stop a session:

{
  "action": "stop",
  "session_id": 1
}

browser_get_context

Lists active Browser MCP sessions with process ID, session ID, title, sanitized URL, and state.

Session states:

browser_run_actions

Runs an async JavaScript function body in the live page. The function receives a browser helper object.

Inspect the current page:

return browser.snapshot();

Navigate:

return browser.navigate("https://example.com");

Click and type:

const input = document.querySelector("input[name=email]");
const rect = input.getBoundingClientRect();
await browser.leftClick(rect.left + 8, rect.top + rect.height / 2);
await browser.type("user@example.com");
return input.value;

Capture a screenshot:

return await browser.screenshot();

Review network activity:

const logs = await browser.networkLogs({ filterMethod: "POST", filterPath: "/api/" });
return await browser.inspectNetworkRequest(logs.requests[0].id);

Available helpers:

Environment variables

Development

Install dependencies:

npm install

Run the app:

npm start

Run the recommended MCP mode from the local checkout:

npm run mcp

Check JavaScript syntax:

npm run check

Run tests:

npm test

The test suite starts a local HTTP test page and a Browser MCP HTTP sentinel, then validates the public MCP tools and browser actions.

Troubleshooting

The MCP client cannot find browser-mcp-electron

Use the npx configuration or provide the absolute path to the binary.

Windows:

where.exe browser-mcp-electron

Linux/macOS:

command -v browser-mcp-electron

The sentinel starts, but the MCP client opens a new one

Make sure both commands use the same user account and, if you pinned a port, the same --sentinel-port value. The sentinel registry is stored in the OS temp directory and is scoped to the current machine/user environment.

Electron does not start on Linux

Install the Electron runtime libraries required by your distribution and start the sentinel from a graphical user session. For systemd, prefer a user service instead of a system service because Browser MCP needs access to the user's desktop session.

A page action times out

Pass a larger timeout_ms to browser_run_actions:

{
  "code": "await browser.sleep(15000); return browser.snapshot();",
  "timeout_ms": 20000
}

Action timeouts are clamped between 100 ms and 5 minutes.

Multiple sessions are active

Pass the session_id returned by browser_toggle_session to browser_run_actions. When more than one session exists, Browser MCP requires explicit session selection.