Browser Tools MCP server

This Model Context Protocol (MCP) server helps AI tools analyze and interact with your browser by capturing console logs, network requests, screenshots, and page elements. It creates a bridge between your browser activities and AI-powered applications.

Installation

Prerequisites

• Chrome browser
• Node.js environment

Setup Process

1. Install the MCP server package:

   npx @agentdeskai/[email protected]
   

2. Download the latest Chrome extension:

   • Get the v1.2.0 BrowserToolsMCP Chrome Extension
   • Unzip and load it in Chrome through developer mode

3. Run the local node server:

   npx @agentdeskai/[email protected]
   

   Note: Always specify the version (1.2.0) when using npx to ensure you get the latest release.

4. Open Chrome DevTools to start sending logs to your server

Usage

Basic Features

The MCP server enables AI tools to:

• Monitor browser console output
• Capture network traffic
• Take screenshots
• Analyze selected DOM elements
• Wipe logs stored in the MCP server

Screenshot Auto-Paste Feature

Enable "Allow Auto-Paste into Cursor" within the DevTools panel to automatically paste screenshots into Cursor. Make sure to focus on the Agent input field in Cursor for this to work.

Audit Tools

The MCP server provides several audit tools that can be triggered with specific queries:

Accessibility Audit

Checks page compliance with WCAG standards:

"Are there any accessibility issues on this page?"
"Run an accessibility audit."

Performance Audit

Identifies loading issues and performance bottlenecks:

"Why is this page loading slowly?"
"Check the performance of this page."

SEO Audit

Evaluates search engine optimization factors:

"How can I improve SEO for this page?"
"Run an SEO audit."

Best Practices Audit

Checks adherence to web development standards:

"Run a best practices audit."
"Are there any best practices issues on this page?"

NextJS Audits

Provides NextJS-specific analysis:

"Run a NextJS audit."
"Run a NextJS audit, I'm using app router."

Special Modes

Audit Mode

Runs all audit tools in sequence:

"Run audit mode."
"Enter audit mode."

Debugger Mode

Executes all debugging tools in sequence:

"Enter debugger mode."

Architecture

The system consists of three main components:

1. Chrome Extension: Captures browser data (screenshots, logs, network activity)
2. Node Server: Middleware that processes data and communicates between components
3. MCP Server: Implements the Model Context Protocol for AI client interaction

┌─────────────┐     ┌──────────────┐     ┌───────────────┐     ┌─────────────┐
│  MCP Client │ ──► │  MCP Server  │ ──► │  Node Server  │ ──► │   Chrome    │
│  (e.g.      │ ◄── │  (Protocol   │ ◄── │ (Middleware)  │ ◄── │  Extension  │
│   Cursor)   │     │   Handler)   │     │               │     │             │
└─────────────┘     └──────────────┘     └───────────────┘     └─────────────┘

All logs are stored locally on your machine and are never sent to any third-party service.

Compatibility

• Works with any MCP-compatible client
• Primary integration with Cursor IDE
• Supports other AI editors and MCP clients

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "browser-tools" '{"command":"npx","args":["@agentdeskai/[email protected]"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "browser-tools": {
            "command": "npx",
            "args": [
                "@agentdeskai/[email protected]"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "browser-tools": {
            "command": "npx",
            "args": [
                "@agentdeskai/[email protected]"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect