Installation

Getting Started

Built by @tedx_ai, BrowserTools MCP streams console output, network activity, screenshots and Lighthouse audits from your real Chrome session — the one already logged into your app — to any MCP-compatible client. That means you can simply tell Cursor, Claude Code or any AI code editor with MCP support:

“This isn’t working… enter debugger mode!"

"Can you edit the currently selected element to do x, y and z?"

"I need to improve SEO and performance… enter audit mode"

"Can you check console and network logs to see what went wrong?"

"Something doesn’t look right in the UI. Can you take a screenshot?”

Version 2.0 is a rewrite. One process instead of three, no unauthenticated local server, and credentials scrubbed before they leave the browser. Coming from 1.x? Read the migration guide — and upgrade, because 1.2.x has a critical vulnerability.

Requirements

Node 22.19 or newer — check with node --version
Google Chrome or a Chromium-based browser
An MCP client (Cursor, Claude Code, Windsurf, Cline, RooCode, Zed, Claude Desktop, Gemini CLI)

If you use nvm, asdf or a similar version manager, make sure your editor inherits the same Node version you see in your terminal. A client launched from the macOS Dock often does not.

There are two pieces: an MCP server (one command) and a Chrome extension. There is no second server to start — in 2.0 the MCP server runs the browser connector itself.

1. Point your MCP client at the server

Most clients take the same JSON. Give the server a name (browser-tools), set the command to npx and the args as below:

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

claude mcp add browser-tools -- npx -y @agentdeskai/browser-tools-mcp@latest

{
  "mcpServers": {
    "browser-tools": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@agentdeskai/browser-tools-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "browser-tools": {
      "command": "wsl",
      "args": ["bash", "-c", "npx -y @agentdeskai/browser-tools-mcp@latest"]
    }
  }
}

Where that JSON goes depends on the client:

Client	Location
Cursor	`.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` globally
Claude Code	Use the `claude mcp add` command above
Claude Desktop	`claude_desktop_config.json`
Windsurf, Cline, RooCode, Zed	See each client’s MCP settings

Use @latest. Earlier versions of these docs pinned @1.2.0. That version contains a critical vulnerability — do not pin to it.

Once configured, confirm the server connected. You should see the tools listed and a green indicator next to the server name. If it does not register, wait a few seconds and refresh. For more on MCP setup, see the docs for these clients:

2. Install the Chrome Extension

Clone the repository, then load the chrome-extension directory as an unpacked extension:

git clone https://github.com/AgentDeskAI/browser-tools-mcp.git

git clone git@github.com:AgentDeskAI/browser-tools-mcp.git

gh repo clone AgentDeskAI/browser-tools-mcp

2a. Open ‘Manage Extensions’

2b. Enable ‘Developer Mode’ and click ‘Load unpacked’

2c. Select the chrome-extension directory inside the repo you just cloned. You should see BrowserToolsMCP in your list of extensions now!

Upgrading from 1.x? Remove the old extension first. The two are not compatible — the wire protocol, permissions and settings all changed.

3. Open the Chrome Developer Console

Right click on any web page and click ‘Inspect’. Capture begins as soon as DevTools is open — in 1.x you had to select the BrowserTools panel first, which is no longer true.

The BrowserTools panel is now only for settings and status. From it you can:

See whether the extension is connected, and to which port
Change the connector host and port, and reconnect
Choose what to capture: console, network, response bodies, request/response headers
Switch console capture mode between the DevTools protocol and wrapping the page console
Grant optional cookie access
Adjust log, query and string size limits

Network capture starts when DevTools opens. Requests that finished before then are not recorded — reload the page to capture a full page load.

4. Check that it works

Run the built-in diagnostic from any terminal:

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. To watch capture happen live, start with --verbose:

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)

Without it the connector only reports connect and disconnect, so a working setup and a silent one look identical.

Congratulations! You’ve successfully installed and configured BrowserTools 🎉 Check out the Quickstart Guide to learn how to use it, or the tools reference for everything your agent can call. Congrats

Troubleshooting

Start with --doctor. It checks every part of the setup and names the one that is broken:

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

If that does not resolve it:

Check that the MCP server registered in your client and shows its tools
Check that the extension is loaded and DevTools is open on the tab you want to capture
Look through the common issues below

And if you’re STILL stuck, run this in a terminal to monitor your client’s MCP logs:

tail -n 20 -F ~/Library/Application\ Support/Cursor/**/*MCP.log

Then contact @tedx_ai on X or open an issue on the Github repo with the --doctor output and those logs, and we’ll get back to you as soon as possible.

Common Issues & Errors

Error: my client says it can't find npx

On Windows, set "command": "cmd" with "args": ["/c", "npx", "-y", "@agentdeskai/browser-tools-mcp@latest"].Elsewhere, this usually means your editor is running a different Node than your terminal. Find the absolute path with which npx and use that as the command.

Error: this package requires Node >=22.19

2.0 requires Node 22.19 or newer — Lighthouse 13 and the current toolchain need it. Upgrade Node, and make sure your editor inherits the new version.

Issue: I'm still being told to run browser-tools-server

You’re following 1.x instructions. In 2.0 the MCP server embeds the connector, so there is no second process. Delete any “start the browser tools server” step from your setup or scripts. See the migration guide.

Issue: Not seeing any logs

Open the Chrome DevTools console in the browser tab you want to capture logs from, then reload the page. Confirm it is working with --verbose, which prints each entry as it arrives.

Issue: The logs are from the wrong tab

Every tab with DevTools open is tracked separately, and tools act on the tab you most recently opened DevTools on. Every result reports the tabId and url it came from, plus otherTabs. Call listBrowserTabs and pass a tabId to target a specific one, or allTabs: true to read across all of them.

Issue: I see [REDACTED] in my logs

That is this tool protecting you, not your app misbehaving. Credential-bearing headers, JWTs, cloud keys and vendor tokens are scrubbed in the browser before they are sent. Pass --no-redact if you genuinely need raw values.

Issue: Cannot see my screenshots

Screenshots are saved to ~/Downloads/mcp-screenshots by default. Set another location with --screenshot-dir <path> or BROWSER_TOOLS_SCREENSHOT_DIR. takeScreenshot also returns the image itself to your agent, plus a browser-tools://screenshot/{name} link.

Issue: Chrome says it started debugging this browser

Console capture defaults to the DevTools protocol, which triggers that banner. Switch the panel’s capture mode to Wrap page console to avoid it. That mode is also the one Firefox uses.

Error: audits fail or no browser is found

Audits launch a separate browser and take up to a minute. Any Chromium-based browser works — Chrome, Chromium, Brave, Edge, Vivaldi, Opera or Arc — and --doctor reports which one will be used. Set CHROME_PATH to point at a specific binary.

Issue: Logs keep disappearing

Captured telemetry lives in memory and is cleared when the server restarts. Retention is per tab, so a chatty page cannot evict the history of the one you care about. wipeLogs clears it deliberately, for a clean reproduction.

Issue: Encountering an unknown error

Contact @tedx_ai or open an issue on the Github repo.

Get Started

Reference

Upgrading & Security

Project

Installation

Getting Started

Requirements

Installation

1. Point your MCP client at the server

2. Install the Chrome Extension

3. Open the Chrome Developer Console

4. Check that it works

Troubleshooting

Common Issues & Errors

​Getting Started

​Requirements

​Installation

​1. Point your MCP client at the server

​2. Install the Chrome Extension

​3. Open the Chrome Developer Console

​4. Check that it works

​Troubleshooting

​Common Issues & Errors

Getting Started

Requirements

Installation

1. Point your MCP client at the server

2. Install the Chrome Extension

3. Open the Chrome Developer Console

4. Check that it works

Troubleshooting

Common Issues & Errors