Configuration

Every flag has a matching BROWSER_TOOLS_* environment variable, so you can configure the server whether your MCP client lets you pass arguments or only environment.

Flags

Flag	Environment variable	Purpose
`--port <n>`	`BROWSER_TOOLS_PORT`	Connector port the extension talks to (default `3025`)
`--host <addr>`	`BROWSER_TOOLS_HOST`	Loopback address to bind (default `127.0.0.1`)
`--screenshot-dir <path>`	`BROWSER_TOOLS_SCREENSHOT_DIR`	Where screenshots are written
`--only <a,b>`	`BROWSER_TOOLS_TOOLS`	Expose only these tools
`--exclude <a,b>`	`BROWSER_TOOLS_EXCLUDE_TOOLS`	Hide these tools
`--connect <url>`	—	Attach to a connector already running elsewhere
`--token <t>`	`BROWSER_TOOLS_TOKEN`	Auth token to use with `--connect`
`--verbose`	`BROWSER_TOOLS_VERBOSE`	Print each captured entry as it arrives
`--no-redact`	`BROWSER_TOOLS_REDACT=false`	Disable credential scrubbing (not recommended)
`--doctor`	—	Check the setup and exit
`--version`, `--help`	—	Print and exit

BROWSER_TOOLS_STATE_DIR and BROWSER_TOOLS_LOG_LEVEL are also honoured. Passing them through an MCP client config looks like this:

{
  "mcpServers": {
    "browser-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@agentdeskai/browser-tools-mcp@latest",
        "--port", "3030",
        "--screenshot-dir", "./screenshots"
      ]
    }
  }
}

A relative --screenshot-dir resolves against the working directory your MCP client launched the server in, which is not always your project. Use an absolute path if you are not sure.

Diagnostics

`--doctor`

The first thing to run when something is not working:

npx @agentdeskai/browser-tools-mcp --doctor

It reports your Node version, whether the connector started, whether the extension is connected, whether the screenshot directory is writable, and which browser audits will use — with a suggested fix for each problem it finds, then exits.

`--verbose`

Watch capture happen as it arrives, which is the fastest way to confirm a fresh install is really working:

npx @agentdeskai/browser-tools-mcp --verbose

· console error tab 42 Uncaught TypeError: total is not a function
· network 500 POST tab 42 https://myapp.local/api/pay (1310ms)

Output goes to stderr, so it is safe to enable on the MCP server without corrupting the JSON-RPC stream, and values are printed after redaction. Without it the connector reports only connect and disconnect, so a working capture and a silent one look identical.

By default the MCP server runs its own connector, which is all you need. If you want several MCP clients — say Cursor and Claude Code at once — reading the same browser session, start the connector once:

npx @agentdeskai/browser-tools-server

Every client then attaches to it automatically. To attach explicitly, or to reach a connector on a non-default port:

npx @agentdeskai/browser-tools-mcp --connect http://127.0.0.1:3025 --token <token>

The connector publishes its port and token to ~/.browser-tools-mcp/session.json, written owner-only (0600), so an MCP process started separately can attach without probing anything. Override the location with BROWSER_TOOLS_STATE_DIR.

If port 3025 is taken, the connector picks the next free port in the 3025–3035 range and the extension discovers it. You do not normally need to set --port.

The extension panel

A few settings live in the browser rather than on the command line, because they control what the extension captures before anything is sent. Open DevTools and select the BrowserTools panel:

Setting	What it controls
Host and port	Which connector to talk to, plus a Reconnect button
Capture console / network	Whether each kind of telemetry is captured at all
Capture response bodies	Whether response payloads are included
Show request / response headers	Off by default, independently per direction
Capture mode	DevTools protocol, or wrapping the page console
Enable cookie access	Grants the optional `cookies` permission
Log, query and string size limits	How much is retained and how much any one value can be

Capture modes

DevTools protocol is richer, and is the default. It makes Chrome display a “started debugging this browser” banner. Wrap page console replaces the page’s console methods instead. No banner, and no dependency on chrome.debugger — at the cost of missing some browser-generated messages the protocol would report.

Firefox is not verified. The extension is written cross-browser and this capture mode is the one a Firefox port would use, but it has never actually been loaded in Firefox and no test covers it. Screenshots use the DevTools protocol and will not work there at all. Treat Firefox as unsupported for now — and if you do try it, a report either way is welcome.

Headers are off by default in both directions, and storage values are withheld unless a tool asks for them. See privacy & security.

Get Started

Reference

Upgrading & Security

Project

Flags

Diagnostics

`--doctor`

`--verbose`

The extension panel

Capture modes

​Flags

​Diagnostics

​--doctor

​--verbose

​Sharing one browser session

​The extension panel

​Capture modes

Flags

Diagnostics

`--doctor`

`--verbose`

Sharing one browser session

The extension panel

Capture modes