browser-tools

BrowserTools MCP integrates a browser monitoring and auditing toolkit with MCP (Model Context Protocol) so AI-powered IDE clients can instruct a local browser-tools extension to capture, analyze, and report on browser data. The MCP server exposes a suite of audit and debugger capabilities (Accessibility, Performance, SEO, Best Practices, NextJS Audits, plus Audit and Debugger Modes) that you can trigger with natural language prompts or predefined queries. Use the MCP client (typically inside your IDE) to send queries like run an accessibility audit or enter audit mode; the server will orchestrate Puppeteer-based headless browser tasks via the connected Chrome extension to return structured results that your tooling can present to users.

Common workflows involve running the BrowserTools MCP alongside the browser-tools-server (the local middleware) and the BrowserTools Chrome extension. The MCP server interprets requests from your IDE, executes the appropriate audit sequence against the active page, and returns a structured JSON with scores, findings, and actionable recommendations. Use the provided example prompts in the docs to trigger specific audits (Accessibility, Performance, SEO, Best Practices) or to run all audits in a defined sequence via Audit Mode or Debugger Mode. Ensure the extension is enabled in the browser and that you have an active tab before issuing audit requests.

Examples of capabilities include: triggering an Accessibility Audit to identify WCAG-related issues, a Performance Audit to surface render-blocking resources and DOM size concerns, a SEO Audit to evaluate metadata and headings, and NextJS-specific audits to surface framework-related optimizations. You can also run combined sequences with Audit Mode or Debugger Mode to perform a full suite of checks in order, receiving a consolidated JSON report for your IDE UI to display.

Prerequisites

• Node.js and npm (or core tooling that provides npx) installed on your development machine
• An IDE or environment capable of issuing MCP queries to an MCP server
• Chrome browser with the BrowserTools extension installed and enabled

Step-by-step installation

1. Install the MCP server within your IDE terminal or command line:

   npx @agentdeskai/browser-tools-mcp@latest

2. Confirm the server is accessible. The MCP server runs locally; ensure there are no port conflicts and that your IDE is configured to communicate with the MCP endpoint.

3. Install and run the accompanying BrowserTools server (the local middleware) as described in the project docs:

   npx @agentdeskai/browser-tools-server@latest

4. Install the Chrome extension for BrowserTools MCP from the release you’re targeting and load it into Chrome.

5. In your IDE, configure the MCP client to point to the running MCP server (the default npx-based invocation should be sufficient if your IDE auto-handles the process).

6. Open a browser tab, enable the BrowserTools extension, and begin issuing MCP queries (e.g., run an Accessibility Audit, run a Performance Audit, etc.).

Notes

• The BrowserTools extension acts as the bridge between the MCP server and the browser to capture data (screenshots, console logs, network activity, DOM elements).
• You may need to restart the local Chrome browser or the local Node server if you encounter connectivity issues.
• Ensure you only have a single instance of the BrowserTools DevTools panel open to avoid conflicts.

Tips and troubleshooting:

• Ensure the BrowserTools extension is enabled and connected before issuing MCP queries.
• If audits seem slow or unresponsive, verify that only one Chrome devtools instance is active and that the extension has permission to operate on the current tab.
• The headless Puppeteer-based audits stay alive for 60 seconds after the last audit call to efficiently handle rapid consecutive requests; plan your queries accordingly.
• If you need NextJS-specific audits, ensure the page is recognized as a NextJS application by the auditing tools so that the appropriate checks are applied.
• When debugging, collect logs from the BrowserTools extension, the MCP server, and the local browser tab to diagnose issues across the extension, server, and IDE.