BrowserTools MCP: Browser Integration for AI Agents

A Model Context Protocol (MCP) server that integrates AI code editors and agents directly with your browser for monitoring, debugging, and auditing web applications.

Overview

BrowserTools MCP is a tool that integrates AI code editors and agents directly with your browser to:

• Monitor console logs, XHR requests, DOM elements, and take screenshots
• Run SEO, performance, and code audits via Lighthouse
• Trigger Debugger or Audit Mode for deeper debugging

This implementation follows the best practices for building MCP servers, allowing seamless integration with any MCP-compatible client like Cursor, Windsurf, RooCode, and others using Claude 3.5 Sonnet as the model.

Features

The server provides the following browser integration tools:

Browser Monitoring

• getConsoleLogs: Get browser console logs
• getConsoleErrors: Get browser console errors
• getNetworkLogs: Get all network requests
• getNetworkErrors: Get failed network requests
• getSelectedElement: Get currently selected DOM element
• takeScreenshot: Capture browser screenshot

Log Management

• wipeLogs: Clear all stored logs

Audit Tools

• runPerformanceAudit: Run Lighthouse performance audit
• runAccessibilityAudit: Run accessibility audit
• runSEOAudit: Run SEO audit
• runBestPracticesAudit: Run best practices audit
• runNextJSAudit: Run Next.js-specific audit

Debug Modes

• runDebuggerMode: Activate browser debugger
• runAuditMode: Run comprehensive audit

Prerequisites

• Docker installed
• Chromium/Chrome browser
• MCP client (e.g., Cursor, Windsurf, RooCode, etc.)
• Chrome Extension (manually loaded)

Installation

Using Docker (Recommended)

Use the following one-line command to deploy the BrowserTools MCP server:

docker run -d \
  --name browser-tools-mcp-server \
  -p 3025:3025 \
  -v $HOME/.browser-tools-mcp:/app/data \
  --restart unless-stopped \
  node:20-alpine sh -c "\
    apk add --no-cache git && \
    git clone https://github.com/AgentDeskAI/browser-tools-mcp.git /app && \
    cd /app && \
    npm install && \
    npx @agentdeskai/browser-tools-server@1.2.0"

Using Node.js Directly

1. Clone this repository:

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

2. Install dependencies:

   npm install
   

3. Create a .env file based on .env.example:

   cp .env.example .env
   

4. Start the server:

   npm start
   

Chrome Extension Setup

Since the extension isn't on Chrome Store yet, follow these steps to install it manually:

1. Clone the repo:

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

2. Open chrome://extensions in your browser

3. Enable Developer Mode

4. Click Load unpacked and select the chrome-extension folder in the repo

Configuration

The following environment variables can be configured in your .env file:

Variable	Description	Example
TRANSPORT	Transport protocol (sse or stdio)	sse
HOST	Host to bind to when using SSE transport	0.0.0.0
PORT	Port to listen on when using SSE transport	3025
DATA_DIR	Directory to store persistent data	./data
VERBOSE	Enable verbose logging	false
EXTENSION_ID	Chrome extension ID
ALLOW_ALL_ORIGINS	Allow all origins for CORS	false
ALLOWED_ORIGINS	Comma-separated list of allowed origins	http://localhost:3000

Running the Server

Using Node.js

SSE Transport

# Set TRANSPORT=sse in .env then:
npm start

The MCP server will run as an API endpoint that you can connect to with the configuration shown below.

Stdio Transport

With stdio, the MCP client itself can spin up the MCP server, so nothing to run at this point.

Using Docker

SSE Transport

docker run --env-file .env -p 3025:3025 -v $HOME/.browser-tools-mcp:/app/data browser-tools-mcp

The MCP server will run as an API endpoint within the container that you can connect to with the configuration shown below.

Stdio Transport

With stdio, the MCP client itself can spin up the MCP server container, so nothing to run at this point.

Integration with MCP Clients

SSE Configuration

Once you have the server running with SSE transport, you can connect to it using this configuration:

{
  "mcpServers": {
    "browser-tools": {
      "transport": "sse",
      "url": "http://localhost:3025/sse"
    }
  }
}

Note for Windsurf users: Use serverUrl instead of url in your configuration:

{
  "mcpServers": {
    "browser-tools": {
      "transport": "sse",
      "serverUrl": "http://localhost:3025/sse"
    }
  }
}

Note for n8n users: Use host.docker.internal instead of localhost since n8n has to reach outside of its own container to the host machine:

So the full URL in the MCP node would be: http://host.docker.internal:3025/sse

Make sure to update the port if you are using a value other than the default 3025.

Node.js with Stdio Configuration

Add this server to your MCP configuration for Claude Desktop, Windsurf, or any other MCP client:

{
  "mcpServers": {
    "browser-tools": {
      "command": "node",
      "args": ["your/path/to/browser-tools-mcp/index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "DATA_DIR": "./data",
        "VERBOSE": "false"
      }
    }
  }
}

Docker with Stdio Configuration

{
  "mcpServers": {
    "browser-tools": {
      "command": "docker",
      "args": ["run", "--rm", "-i", 
               "-e", "TRANSPORT=stdio", 
               "-e", "DATA_DIR=/app/data", 
               "-e", "VERBOSE=false", 
               "-v", "$HOME/.browser-tools-mcp:/app/data",
               "browser-tools-mcp"],
      "env": {}
    }
  }
}

Usage Examples

Once the BrowserTools MCP server is running and connected to your AI agent, you can use commands like:

• "Enter debugger mode"
• "Take a screenshot of the UI"
• "Check network logs for errors"
• "Run a performance audit"
• "Check console errors"
• "Get the selected element"

Troubleshooting

Chrome Extension Not Connecting

If the Chrome extension is not connecting to the MCP server:

1. Make sure the MCP server is running
2. Check that the extension is properly installed
3. Verify that the extension has the correct server URL
4. Try restarting Chrome

MCP Server Not Starting

If the MCP server fails to start:

1. Check that the port is not already in use
2. Verify that all dependencies are installed
3. Check the logs for any error messages

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Credits

Powered by @tedx_ai

## Building Your Own Server

This template provides a foundation for building more complex MCP servers. To build your own:

1. Add your own tools by creating methods with the `@mcp.tool()` decorator
2. Create your own lifespan function to add your own dependencies (clients, database connections, etc.)
3. Modify the `utils.py` file for any helper functions you need for your MCP server
4. Feel free to add prompts and resources as well  with `@mcp.resource()` and `@mcp.prompt()`