​
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
  • Currently selected DOM elements

That way, you can simply tell Cursor or any AI code editor with MCP integrations:

“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?"
"Can you edit the currently selected element to do x, y and z?”

​
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’

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

    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!

  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’

    3b. Go to Features, scroll down to MCP Servers and click on ‘Add new MCP server’

    3c. Give it a unique name (browser-tools), set type to ‘command’ and set command to:

    npx @agentdeskai/browser-tools-mcp@1.0.11

    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.

    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

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.

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!

​
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 command in a new terminal and that it says:

    Aggregator listening on http://127.0.0.1:3025

  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

Quickstart