​
Getting Started

Built by @tedx_ai, BrowserTools gives AI code editors and agents the ability to monitor and interact with your web browser for highly effective debugging and a more seamless developer experience - all in a safe and secure manner. With this MCP server tool, you can enable AI code editors and agents to have access to:
  • Console logs and errors
  • XHR network requests/responses
  • Screenshot capabilities w/ optional auto-paste into Cursor
  • Currently selected DOM elements
  • Run SEO, Performance & Code Quality Scans via Lighthouse
  • Run a NextJS-specific SEO audit
  • Enter into “Debugger Mode” which uses many tools + prompts to fix bugs
  • Enter into “Audit Mode” to perform a comprehensive web app audit
That way, you can simply tell Cursor or any AI code editor with MCP integrations:
“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?”

​
Requirements

  • NodeJS installed on your machine
  • Google Chrome or a Chromium-based Browser
  • MCP Client Application (Cursor, Windsurf, RooCode, Cline, Continue, Zed, Claude Desktop)
Note: Model Context Protocol (MCP) is specific to Anthropic models. When using an editor like Cursor, make sure to enable composer agent with Claude 3.5 Sonnet selected as the model.

​
Installation

  1. Download the Chrome Extension: The official chrome extension is pending approval on the Google extension marketplace. For now, you can click here to download the extension or clone the repo below and find the extension within the chrome-extension directory:
    1a. Optionally download from Github 
    git clone https://github.com/AgentDeskAI/browser-tools-mcp.git
  1. Install the Chrome Extension: Open the ‘Manage Extensions’ window, enable ‘Developer Mode’ and then load the unpacked extension:
    2a. Open ‘Manage Extensions’
    Open the Manage Extensions Screen
    2b. Enable ‘Developer Mode’ and click ‘Load unpacked’
    Manage & Load Chrome Extensions
    2c. Navigate to the chrome extension folder downloaded earlier, make sure it’s unzipped and click ‘Select’. You should see BrowserToolsMCP in your list of extensions now!
    Select & Load Unpacked Chrome Extension
  1. Setup BrowserTools MCP Tool: Setup BrowserTools MCP server in your favorite MCP client. Here’s how to set this up inside of Cursor:
    3a. Go to your ‘Cursor Settings’
    Open Cursor Settings
    3b. Go to Features, scroll down to MCP Servers and click on ‘Add new MCP server’
    Go to Cursor Features
    3c. Give it a unique name (browser-tools), set type to ‘command’ and set command to: 
    npx @agentdeskai/browser-tools-mcp@1.2.0
    If using NPX on Windows, use this command to find the path to NPX: 
    which npx
    Add the MCP Tool
    3d. Confirm that the MCP server has been connected. You should see all the tools listed and a green circle next to the tool name.
    Wait a few seconds or click on the refresh button a few times if it does not register. If it still won’t register make sure you entered the right command.
    Confirm the tools are registered
    For more on this, check out the docs for these MCP clients:
  1. Run the BrowserTools Server: Aggregates logs from the chrome extension and sets up websockets for screenshot capture. Run this from your terminal within any directory:
npx @agentdeskai/browser-tools-server@1.2.0
Note: The browser-tools-server runs on port 3025. Make sure to terminate any processes running on this port. In a future release, we will handle this gracefully.
  1. Open the Chrome Developer Console: Right click on any web page and click ‘Inspect’ to open the Chrome dev tools. Once open, logs will be accessible to the MCP client.
Dev Tools
You can navigate to the BrowserTools panel to:
  • Manually capture a screenshot
  • Define a path to save screenshots to (defaults to: Downloads/mcp-screenshots)
  • Wipe all saved logs
  • Modify logging size limits / truncation
Note: Logs will be wiped from the server everytime you refresh the page. You can manually wipe the logs by clicking the ‘Wipe Logs’ button in the BrowserTools panel.
Congratulations! You’ve successfully installed and configured BrowserTools 🎉 Check out our Quickstart Guide to learn how to interact with your new MCP tool! Congrats

​
Troubleshooting

Sometimes things go wrong but we’re here to help! Here are few common gotchas and steps you can take to get BrowserTools up and running:
  1. Check to see if you’ve installed the MCP server into Cursor correctly
  2. Make sure you’re running the @agentdeskai/browser-tools-server@1.2.0 command in a new terminal
  3. Make sure you’ve installed the chrome extension and opened chrome dev tools in the tab you want to capture logs from
  4. If none of this works double-check the common gotchas below
And if you’re STILL stuck…
  1. Run this command in a new terminal to monitor the Cursor MCP logs:
tail -n 20 -F ~/Library/Application\ Support/Cursor/**/*MCP.log
  1. Take a screenshot of those logs, a screenshot of the node server logs from browser-tools-server and if possible - go into the manage extensions window in chrome and click on an error button if present in the extension we installed earlier to capture a screenshot of that too
  2. Contact @tedx_ai on X or add an issue to the Github repo with all the requested details and we’ll get back to you as soon as possible!

​
Common Issues & Errors