Contribution - Running BrowserTools MCP on Windows with Cursor - A Help Guide.

[SDJINC]

BrowserTools MCP: Windows Installation Guide

This guide focuses specifically on installing and running BrowserTools MCP on Windows systems. I am simply a hobbyist using these tools so I thought I would add this here for others who might not be very technical to help set this up.

To Agent Desk AI Team - Thank you for creating this.

Overview

BrowserTools MCP allows Cursor and other AI code editors to interact with your browser, providing access to:

• Console logs and errors
• Network requests and responses
• Screenshots
• DOM elements

Prerequisites

• Windows 10 or 11
• Google Chrome browser
• Node.js installed
• Cursor IDE (or other MCP-compatible editor)

Installation Steps

1. Clone or Download the Repository

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

2. Build the Components

Build both the middleware server and MCP server components:

# Build the middleware server
cd browser-tools-server
npm install
npm run build


# Build the MCP server
cd ../browser-tools-mcp
npm install
npm run build

3. Install the Chrome Extension

1. Open Chrome
2. Navigate to chrome://extensions/
3. Enable "Developer mode" (toggle in top-right corner)
4. Click "Load unpacked"
5. Browse to the chrome-extension folder in the repository
6. Select the folder and click "Open"

Verify that "BrowserToolsMCP" appears in your extensions list.

4. Create a Startup Batch File

Create a file named start-browser-tools.bat in your repository folder with the following content:

@echo off
title BrowserTools Middleware Launcher
echo Starting BrowserTools middleware component...

:: Define port number for middleware
set MIDDLEWARE_PORT=3026

:: First, let's stop any existing process that might be running our middleware server
echo Stopping any existing middleware processes...
for /f "tokens=5" %%a in ('netstat -ano ^| findstr ":%MIDDLEWARE_PORT% "') do (
    echo Found process on port %MIDDLEWARE_PORT%: %%a
    taskkill /F /PID %%a /T 2>nul
    if %errorlevel% equ 0 (
        echo Successfully terminated process %%a
    ) else (
        echo Could not terminate process %%a
    )
)

:: Wait a moment for port to be freed
timeout /t 2 /nobreak > nul

:: Check if Middleware Server port is already in use
netstat -ano | findstr ":%MIDDLEWARE_PORT%" >nul
if %errorlevel% equ 0 (
  echo Middleware Server port %MIDDLEWARE_PORT% is still in use.
  echo Please check task manager and end any node.js processes.
  echo Press any key to exit...
  pause >nul
  exit
) else (
  echo Starting Middleware Server on port %MIDDLEWARE_PORT%...
  start "BrowserTools Middleware Server" cmd /c "node %CD%\browser-tools-server\dist\browser-connector.js --port %MIDDLEWARE_PORT%"
)

echo BrowserTools middleware started!
echo.
echo Remember to:
echo 1. Install the Chrome extension
echo 2. Open Chrome DevTools
echo 3. Configure Cursor with MCP command: node %CD%\browser-tools-mcp\dist\mcp-server.js
echo.
echo Press any key to exit...
pause >nul

5. Configure Cursor (or your MCP-compatible editor)

1. Open Cursor
2. Go to Settings (gear icon)
3. Navigate to Features
4. Scroll down to MCP Servers
5. Click "Add new MCP server" with these settings:
   • Name: browser-tools
   • Type: command
   • Command: node [FULL_PATH]\browser-tools-mcp\dist\mcp-server.js

Replace [FULL_PATH] with the full path to your repository location (e.g., E:\mcp\BrowserToolsMCP).

6. Running BrowserTools

Proper sequence for using BrowserTools on Windows:

1. Run the start-browser-tools.bat file to start the middleware server

   • This will open a new command window for the middleware server
   • The original batch file window can be closed after pressing any key

2. Open Chrome and navigate to the page you want to monitor

3. Open Chrome DevTools

   • Press F12 or right-click and select "Inspect"
   • Make sure you can see the "BrowserTools" tab in DevTools

4. Use Cursor with the MCP tools

   • Cursor will start the MCP server automatically
   • This will open another command window for the MCP server

Troubleshooting Windows-Specific Issues

Command Window Management

Expected behavior: You should have exactly 2 command windows running:

1. Middleware Server window
2. MCP Server window (started by Cursor)

If you see more windows, something is misconfigured.

Path Issues

Windows paths use backslashes (\) which can cause issues in configuration. Make sure to:

• Use full paths in your Cursor MCP configuration
• Either escape backslashes (\\) or use quoted paths

Port Conflicts

If you see errors about addresses already in use:

1. Check Task Manager for node.js processes
2. End any node.js processes that might be using ports 3025 or 3026
3. Try running the batch file again

NPX vs. Direct Node Commands

While the repository documentation recommends using NPX commands:

npx @agentdeskai/[email protected]

Windows often works better with direct node commands:

node [PATH]\browser-tools-mcp\dist\mcp-server.js

Anti-Virus Interference

Some Windows anti-virus software may block WebSocket connections. If you experience connection issues:

1. Check your anti-virus logs
2. Add exceptions for node.js and the BrowserTools directories

Verifying Your Setup

To confirm everything is working correctly:

1. In Chrome, create a simple console log: open DevTools and type console.log("Test message") in the Console tab

2. In Cursor, ask:

   Can you check the browser console logs?
   

3. Cursor should respond with your test message

4. Try a screenshot command:

   Take a screenshot of the current browser tab
   

Creating a Desktop Shortcut (Optional)

1. Right-click on your desktop
2. Select New > Shortcut
3. Browse to your start-browser-tools.bat file
4. Name it "BrowserTools MCP"

This gives you one-click access to start the middleware server.

[Fabio286]

The guide misses that you have to run npm run build, either in browser-tools-mcp or browser-tools-server.

[moadel321]

Thank you for the guide. just added npm run build and things ran smoothly
I used the 'node' command, but for other MCP servers on Windows (and using Cursor) adding the flag '/k' did get the npx to work for me

like the following
"Jina": {
"command": "cmd",
"args": [
"/k",
"npx",
"-y",
"@smithery/cli@latest",
"run",
"jina-ai-mcp-server",
"--config",
""{\"jinaApiKey\":\"APIkeyHere\"}""
]
},

[jmanhype]

Thank You For This Windows Guide!

This is an excellent and comprehensive guide for Windows users. I've found that a similar approach works for macOS and Linux users as well.

For macOS Users (Complementary Information):

1. Find your package locations with:

   find ~/.npm/_npx -name "browser-tools-mcp" -type d

2. Configure Cursor with direct paths:

   "BrowserTools": {
     "command": "/opt/homebrew/bin/node",
     "args": [
       "/Users/YOUR_USERNAME/.npm/_npx/HASH_DIRECTORY/node_modules/@agentdeskai/browser-tools-mcp/dist/mcp-server.js",
       "run"
     ]
   }

3. Follow the same principles outlined in this guide:

   • Run the middleware server first
   • Ensure Chrome DevTools is open
   • Use direct file paths and executables
   • Match the pattern used by other working MCP tools

The key insight from this guide that applies across platforms is to use direct paths to Node and the server JS files instead of relying on NPX commands, which can sometimes fail due to environment and path resolution issues.

[sbdeals]

I would appreciate a damn walkthrough. I have been trying to integrate this into windows 10 for 4 hours now. npx, node, downloding the files from git or even writing them in myself - the middleware server seems to be running fine but the data being sent to claude is in text form not JSON.

[arm5472]

Within settings MCP tab I only see "+ Add new global MCP server" and when I click it wants to create a mcp.json file and let me edit it to add an MCP server. There is no UI or dialog to add an MCP server!

I have added the MCP server as json, but Cursor doesn't recognise it. I cannot see a green dot to make sure it is working.

Version: 0.47.8 (user setup)
VSCode Version: 1.96.2
Commit: 82ef0f61c01d079d1b7e5ab04d88499d5af500e0
Date: 2025-03-18T05:39:50.993Z
Electron: 32.2.6
Chromium: 128.0.6613.186
Node.js: 20.18.1
V8: 12.8.374.38-electron.0
OS: Windows_NT x64 10.0.26100

[DevBrain888]

Thank you for guide

when you are click on the button cursor ai will offer create mcp.json. You are paste this json code for work if u use windows.

{
    "mcpServers": {
      "browser-tools": {
        "command": "cmd /c npx -y @agentdeskai/[email protected]",
        "args": [
          
        ],
        "enabled": true
      }
    }
  }

Windows will create a new terminal window, do not close this window so that the server does not terminate the MCP.

[moghribalakrishna]

Thank you DevBrain it worked

[SDJINC]

The new cursor update has either removed the popup to add it and made it json editable.

Mine is simple as this.

{
  "mcpServers": {
    "browser-tools-mcp-local": {
      "command": "node",
      "args": [
        "X:\\mcp\\BrowserToolsMCP\\browser-tools-mcp\\dist\\mcp-server.js"
      ]
    }
  }
}

[raysuelzer]

Anyone else see connectione errors starting the server?

2025-04-05 22:41:28.586 [info] ools: Handling ListOfferings action
2025-04-05 22:41:28.587 [error] ools: No server info found
2025-04-05 22:42:27.618 [info] ools: Handling ReloadClient action
2025-04-05 22:42:27.618 [info] ools: getOrCreateClient for stdio server. process.platform: win32 isElectron: true
2025-04-05 22:42:27.618 [info] ools: Starting new stdio process with command: cmd /c npx -y @agentdeskai/[email protected]
2025-04-05 22:42:29.926 [info] ools: Client closed for command
2025-04-05 22:42:29.926 [error] ools: Error in MCP: Client closed
2025-04-05 22:42:29.927 [error] ools: Failed to reload client: MCP error -32000: Connection closed
2025-04-05 22:42:29.928 [info] ools: Handling ListOfferings action
2025-04-05 22:42:29.928 [error] ools: No server info found

[kidandcat]

I'm getting that error too.

My MCP is working with AI SDK without issues. Also it is a compiled binary (Golang) with no external dependencies, so no shell needed, no npx, nothing.

The error is 100% on Cursor side.

2025-04-15 23:40:41.623 [info] echa: Handling CallTool action for tool 'screenshot'
2025-04-15 23:40:41.623 [info] echa: Calling tool 'screenshot'
2025-04-15 23:40:41.623 [debug] Tool arguments: {"path":"/index.html"}
2025-04-15 23:40:41.623 [info] echa: getOrCreateClient for stdio server.  process.platform: darwin isElectron: true
2025-04-15 23:40:41.623 [info] echa: Reusing existing stdio client
2025-04-15 23:40:43.827 [info] echa: Client closed for command
2025-04-15 23:40:43.827 [error] echa: Error in MCP: Client closed
2025-04-15 23:40:43.827 [error] echa: Error calling tool 'screenshot': MCP error -32000: Connection closed

[john-savepoint]

oh my, is this the most annoying mess of confusing instructions. I know cursor changes every week, but change with it please. It is so damn difficult to install this. Been at it for hours, there is different instruction in here, in its comment section, let alone on the official docs, let alone on the insturctional videos.

[vbalashi]

I have issues with taking screenshot:

any ideas?