@krakerxyz/browser-mcp

MCP server package for remote browser automation.

@krakerxyz/browser-mcp is the MCP-facing bridge your AI tool runs locally.

It is designed to be launched by an MCP host (for example from .mcp.json) and connects that host to a Browser MCP backend over WebSocket.

What it is used for

• Give MCP-compatible assistants access to a real Chromium browser session
• Support browser actions such as opening pages, navigation, DOM reads, JS execution, clicks, and screenshots
• Keep reusable named sessions on the server so reconnects can continue prior work
• Reach local/dev-only services through optional tunnel ports

Session model

A session is an isolated browser instance (browser context) on the server.

• Each session keeps its own pages and state isolated from other sessions
• Anonymous sessions are created when no --name is provided
• Named sessions let you reconnect to that same isolated browser context later

How it works

1. Your MCP host starts this package over stdio.
2. This package connects to a Browser MCP server (ws://.../ws/client).
3. On connect, it discovers tools from the server and registers them dynamically.
4. MCP tool calls are forwarded to the remote browser backend.
5. Results are returned to your MCP host over stdio.

This means new server tools can be added without requiring a matching MCP package release.

MCP host configuration (.mcp.json)

Minimal example:

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": [
        "-y",
        "@krakerxyz/browser-mcp",
        "--server",
        "ws://localhost:3100",
        "--api-key",
        "change-me"
      ]
    }
  }
}

Configuration options

• --server <ws-url> (required): Browser MCP server URL, for example ws://localhost:3100
• --api-key <key> (optional): Required when the server has API_KEY enabled
• --name <session-name> (optional): Reuses a named remote session instead of always creating a new anonymous one
• --tunnel-port <port> (optional, repeatable): Enables localhost tunneling for specific ports

Named sessions

When you set --name, the server associates your connection with that session name.

• Reconnecting with the same name resumes that named session when available
• Multiple MCP clients can connect to the same named session at the same time and share that browser state
• Tunnel ports must be decided when the named session is first created (you cannot add tunneling later to an existing non-tunneled session)
• This is useful for long-lived workflows where tabs/session state should survive MCP host restarts or reconnects

Named session .mcp.json example:

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": [
        "-y",
        "@krakerxyz/browser-mcp",
        "--server",
        "ws://localhost:3100",
        "--api-key",
        "change-me",
        "--name",
        "my-workspace"
      ]
    }
  }
}

Tunnel ports

Tunnel ports let the remote browser reach services that are only accessible from the MCP host machine (for example local dev servers).

Example: with --tunnel-port 3000, browsing to http://localhost:3000 in the remote browser is tunneled to port 3000 on the MCP host.

Multiple tunnel ports are supported by repeating --tunnel-port.

Tunnel .mcp.json example:

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": [
        "-y",
        "@krakerxyz/browser-mcp",
        "--server",
        "ws://localhost:3100",
        "--api-key",
        "change-me",
        "--tunnel-port",
        "3000",
        "--tunnel-port",
        "5173"
      ]
    }
  }
}

Available tools

Tools are discovered dynamically from the server on connect. The current set of tools provided by the server:

| Tool | Description | |------|-------------| | browser_open_page | Open a new browser page and navigate to a URL | | browser_close_page | Close a browser page | | browser_list_pages | List all open pages in the current browser session | | browser_navigate | Navigate an existing page to a new URL | | browser_execute_js | Execute JavaScript in a page context. Expression must return a JSON-serializable value. | | browser_get_dom | Get DOM HTML content. Returns full page HTML or matching elements for a CSS selector. | | browser_capture_screenshot | Capture a screenshot of a page. Returns both an inline image and a downloadable URL. | | browser_click | Click on an element by CSS selector or coordinates | | browser_set_cookies | Set one or more cookies in the current browser session context. Supports HttpOnly/Secure cookies. | | browser_get_cookies | Get cookies from the current browser session context. |

Because tools are registered dynamically from the server, new tools added to the server become available to the MCP host without requiring a new release of this package.

Server setup (Docker Compose)

services:
  browser-mcp:
    image: joshkrak/browser-mcp:latest
    container_name: browser-mcp
    restart: unless-stopped
    ports:
      - "3100:3100"
    environment:
      API_KEY: "${BROWSER_MCP_API_KEY}"
    volumes:
      - browser-mcp-data:/data

volumes:
  browser-mcp-data:

If your MCP host is not on the same machine as Docker, replace ws://localhost:3100 with your reachable server URL.