BrowserTools MCP Server

What is BrowserTools MCP Server?

BrowserTools MCP Server is a browser MCP server from AgentDeskAI that streams console logs, network requests, screenshots and Lighthouse audits from your real, logged-in Chrome session to AI coding agents such as Cursor, Claude Code and Windsurf.

It works through a Chrome DevTools extension rather than by launching a separate automated browser, so your agent sees the same page you are debugging, with your existing logins. Version 2.0 (npm @agentdeskai/browser-tools-mcp, 2.0.2 at the time of writing) is a full rewrite: one process instead of three, a loopback-only authenticated connector, and credential scrubbing. The project is open source under the MIT license.

How to use BrowserTools MCP Server?

Setup has two parts: the MCP server (one npx command) and the Chrome extension.

Prerequisites: Node.js 22.19 or newer (check with node --version; if you use nvm or asdf, make sure your editor inherits the same version) and Google Chrome or another Chromium-based browser. No API key is required.

1. Add the MCP server to your client

This is the configuration from the README, and it works in any client that accepts a standard mcpServers block:

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

On Windows, if your client cannot find npx, use "command": "cmd" with "args": ["/c", "npx", "-y", "@agentdeskai/browser-tools-mcp@latest"].

2. Load the Chrome extension

1. Download or clone the browser-tools-mcp repository.
2. Open chrome://extensions and turn on Developer mode.
3. Click Load unpacked and select the chrome-extension directory.

You do not need to start a second server. In 2.0 the MCP server runs the connector itself.

3. Open DevTools and ask your agent

Open Chrome DevTools (F12) on the page you want to inspect. Capture starts as soon as DevTools is open; the BrowserTools panel is only for settings and status. Then ask something like "check the console for errors".

Claude Code

Register the same command with the Claude Code CLI:

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

Cursor

Add the JSON block above to your Cursor MCP configuration (.cursor/mcp.json in a project, or ~/.cursor/mcp.json globally), then reload Cursor.

Windsurf

Add the same mcpServers block to Windsurf's MCP configuration and refresh the server list.

Key features of BrowserTools MCP Server

• Works with your real session: attaches through a DevTools extension, so you stay logged in on the page you were already on. The README notes that since Chrome 136, remote debugging is refused on the default profile, which is why CDP-based servers use a fresh profile.
• Console and network capture: console output, uncaught exceptions, and XHR/fetch requests with status, timing and bodies.
• Screenshots returned as images, plus the saved file path, with a byte budget (3 MB by default) so captures fit in the model's context.
• Lighthouse audits for accessibility, performance (with Core Web Vitals), SEO and best practices.
• Multi-tab aware: every tab with DevTools open is tracked separately, and every result reports the tabId and url it came from.
• Context-friendly output: limit/offset paging, keyword filters, structured output schemas, and MCP resources (including a HAR 1.2 export) for large payloads.
• Privacy by default: loopback-only connector, per-run auth token, and redaction of Authorization/Cookie headers, JWTs and cloud keys.
• Configurable: flags such as --port (default 3025), --screenshot-dir, --only, --exclude and --doctor, or the matching BROWSER_TOOLS_* environment variables.

BrowserTools MCP Server tools

These browser tools MCP functions fall into four groups:

• Console logs: getConsoleLogs and getConsoleErrors return console output and errors, filterable with keywords, limit and offset.
• Network: getNetworkLogs and getNetworkErrors return requests or only failed and 4xx/5xx ones, filterable with urlKeywords and bodyKeywords.
• Page and browser state: getSelectedElement (the element selected in the Elements panel), getPageInfo, getConnectionStatus, listBrowserTabs, takeScreenshot, refreshBrowser, getBrowserStorage (localStorage, sessionStorage and cookies, with values withheld unless requested) and wipeLogs.
• Audits: runAccessibilityAudit, runPerformanceAudit, runSEOAudit and runBestPracticesAudit run Lighthouse in a separate headless browser.

Three MCP prompts, debuggerMode, auditMode and nextjsSeoAudit, give the agent a step-by-step debugging or audit workflow. In 1.x these were tools.

Use cases of BrowserTools MCP Server

• Debug front-end errors without copy-pasting: "Check the console for errors on this page and fix the component that throws them."
• Investigate failing API calls: "Show me the network errors for /api/ requests and explain why the POST returns 500."
• Accessibility checks while you code: "Run an accessibility audit on this page and fix the critical issues."
• Performance and SEO reviews: "Run a performance audit and tell me what is hurting Core Web Vitals," or use the nextjsSeoAudit prompt on a Next.js app.
• Visual verification behind a login: "Take a screenshot of the current tab and check whether the layout broke after my CSS change."

BrowserTools MCP Server vs alternatives

• Playwright MCP, Puppeteer MCP Server and Chrome DevTools MCP: these drive a fresh, automated browser, which suits writing tests and scripted automation. BrowserTools observes the browser you are already using and adds Lighthouse audits, but it does not click or fill forms for you.
• Browser MCP (browsermcp.io): a different project despite the similar name. It is also an MCP server plus Chrome extension that uses your existing browser profile, but it is built for automating the browser (adapted from Playwright MCP), while BrowserTools focuses on debugging telemetry and audits. If you searched "browser mcp" and want the agent to drive pages, Browser MCP or Playwright MCP is a better fit.

Troubleshooting BrowserTools MCP Server

• Nothing is captured: run npx @agentdeskai/browser-tools-mcp --doctor. It reports your Node version, whether the connector started, whether the extension is connected, and whether the screenshot directory is writable.
• Install fails with an engines error: 2.0 declares Node 22.19+ in engines, so an older Node fails at install. Upgrade Node and make sure your editor inherits that version.
• Missing requests from page load: network capture starts when DevTools opens. Reload the page to capture a full load.
• "Started debugging this browser" banner: console capture defaults to the DevTools protocol. Switch the panel's capture mode to Wrap page console.
• Upgrading from 1.x: remove the old extension and load the new chrome-extension directory, and delete any step that starts browser-tools-server separately. See MIGRATION.md in the repo.