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

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>]

| Option | Description | | --- | --- | | --mcp | Starts or reuses the local HTTP sentinel and proxies MCP over stdin/stdout. Recommended for MCP clients. | | --mcp-http | Starts or reuses only the local HTTP MCP sentinel and keeps the process alive. | | --mcp-http-background | Starts or reuses the local HTTP MCP sentinel, then returns after it is healthy. | | --mcp-stdio | Starts the legacy MCP server directly over stdin/stdout. | | --url, -u | Initial browser URL. Defaults to https://www.google.com. | | --data-dir | Browser profile/session directory. Defaults to ~/.browser-mcp. | | --sentinel-port | Port for the HTTP sentinel. Defaults to 0, which means a random available port. | | --help, -h | Prints the CLI help. |

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:

| State | Meaning | | --- | --- | | idle | Ready for actions. | | waiting | Loading or running an action. | | user_input | A JavaScript dialog is pending. Resolve it with browser.setDialog(...) or browser.dismissDialog(). |

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("[email protected]");
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:

| Helper | Description | | --- | --- | | browser.navigate(url) | Schedules navigation after the script returns. | | browser.leftClick(x, y, duration?) | Dispatches a left click at viewport coordinates. | | browser.rightClick(x, y, duration?) | Dispatches a right click at viewport coordinates. | | browser.hover(x, y) | Moves the pointer over a viewport coordinate. | | browser.drag(fromX, fromY, toX, toY, duration?, isLeftClick?) | Drags between viewport coordinates. | | browser.scroll(x, y, delta) | Scrolls at a viewport coordinate. | | browser.type(text) | Types into the focused input, textarea, or contenteditable element. | | browser.sleep(ms) | Waits inside the page action. | | browser.snapshot() | Returns visible text, element hints, console issue counts, and viewport coordinates. | | browser.screenshot() | Returns an MCP image. | | browser.consoleLogs() | Returns recent console logs, warnings, and errors. | | browser.networkLogs(options?) | Returns compact recent network requests. | | browser.inspectNetworkRequest(id) | Returns detailed request/response information for a network request. | | browser.setDialog(value) | Accepts a pending alert/confirm/prompt. | | browser.dismissDialog() | Dismisses a pending alert/confirm/prompt. |

Environment variables

| Variable | Description | Default | | --- | --- | --- | | BROWSER_MCP_DATA_DIR | Browser profile/session directory. | ~/.browser-mcp | | BROWSER_MCP_URL | Initial browser URL. | https://www.google.com | | BROWSER_MCP_SENTINEL_PORT | HTTP sentinel port. Use 0 for a random available port. | 0 | | BROWSER_MCP_DEBUG_LOG | Debug log path used by the launcher and Electron host. | OS temp file | | BROWSER_MCP_RPC_PORT | Internal RPC port for detached Electron host mode. | unset | | BROWSER_MCP_RPC_TOKEN | Internal RPC token for detached Electron host mode. | unset |

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.