Browser MCP

About

Browser MCP is an MCP server + browser extension that allows you to automate your browser using AI applications like VS Code, Claude, Cursor, and Windsurf. Supports both Chrome and Firefox.

This is a fork of the original Browser MCP with the following changes:

• Standalone build: All monorepo dependencies (@repo/*, @r2r/messaging) replaced with local implementations

• Extended toolset: 39 tools (up from 12 core tools) including tab management, JavaScript execution, cookie/storage access, CSS injection, network monitoring, and more

• Cross-browser extension: Full-featured extension with all 36 command handlers, compatible with both Chrome (MV3) and Firefox (MV3)

• WSL support: Auto-detects WSL IP and writes a config file for the extension to discover the correct WebSocket address

• Connection resilience: Speed guidance in tool descriptions, connection error detection with retry hints

Related MCP server: agent-browser-mcp-server

Features

• ⚡ Fast: Automation happens locally on your machine, resulting in better performance without network latency.

• 🔒 Private: Since automation happens locally, your browser activity stays on your device and isn't sent to remote servers.

• 👤 Logged In: Uses your existing browser profile, keeping you logged into all your services.

• 🥷🏼 Stealth: Avoids basic bot detection and CAPTCHAs by using your real browser fingerprint.

Installation

Prerequisites

• Node.js >= 18

• Google Chrome, Chromium, or Firefox 113+

• The Browser MCP extension (included in extension/)

From source

git clone https://github.com/IlGabbia998/browsermcp-mcp.git
cd browsermcp-mcp
npm install
npm run build

Load the extension

Chrome

1. Open Chrome and navigate to chrome://extensions

2. Enable Developer mode

3. Click Load unpacked and select the extension/ folder from this project

4. The extension will show in your toolbar — click it and hit Reconnect when the MCP server is running

Firefox

Firefox MV3 requires a different background entry than Chrome. You must switch the manifest before loading the extension.

Using the helper script (recommended):

npm run use:firefox

Or manually:

1. Copy extension/manifest.firefox.json to extension/manifest.json (replacing the Chrome one)

Then load it:

2. Open Firefox and navigate to about:debugging#/runtime/this-firefox

3. Click Load Temporary Add-on...

4. Select extension/manifest.json from this project

5. The extension will show in your toolbar — click it and hit Connect when the MCP server is running

Note: Chrome and Firefox use different manifest formats for MV3. Use manifest.json for Chrome (default) and run npm run use:firefox (or copy manifest.firefox.json) for Firefox. Firefox temporary add-ons are removed when Firefox is restarted. To restore the Chrome manifest, run npm run use:chrome.

Using in your MCP client

Add the server to your MCP client config. The built entry point is dist/index.js.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/absolute/path/to/browsermcp-mcp/dist/index.js"]
    }
  }
}

opencode

Add to your opencode.json:

{
  "mcp": {
    "browser": {
      "type": "local",
      "command": ["node", "/absolute/path/to/browsermcp-mcp/dist/index.js"],
      "enabled": true
    }
  }
}

Cursor / Windsurf

Add to your MCP settings (.cursor/mcp.json or equivalent):

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/absolute/path/to/browsermcp-mcp/dist/index.js"]
    }
  }
}

Connect the browser

1. Start the MCP server (via your MCP client or node dist/index.js)

2. Open Chrome/Firefox and click the Browser MCP extension icon in the toolbar

3. Click Reconnect — the extension auto-discovers the server address

4. The MCP server will detect the connection automatically

Available Tools (39)

Core

Navigation & Tabs

Page Interaction

Storage & Cookies

Monitoring

Usage examples

Ask your AI assistant to do things like:

• "Go to github.com and take a screenshot"

• "Click the login button and fill in my email"

• "Scroll down and click the next page link"

• "Extract all links from this page"

• "Show me the cookies for this site"

• "Run JavaScript to get the page title"

• "Monitor network requests while I navigate"

• "Inject a custom CSS theme on this page"

The AI uses accessibility snapshots to understand the page structure and interact with elements reliably.

Contributing

This is a standalone build of the Browser MCP server, extracted from the original monorepo. All monorepo dependencies have been replaced with local implementations.

Project structure

src/
  index.ts              # Entry point, tool registration
  server.ts             # MCP server with connection error handling
  context.ts            # WebSocket context management
  ws.ts                 # WebSocket server creation
  lib/
    config/             # App and MCP configuration
    messaging/          # WebSocket message sender
    types/              # Zod schemas for all tools
  tools/
    snapshot.ts         # Core interaction tools (click, type, hover, etc.)
    common.ts           # Navigation tools (navigate, goBack, etc.)
    custom.ts           # Screenshot, console logs
    extended.ts         # All extended tools (26 new tools)
    tool.ts             # Tool type definitions
  utils/
    port.ts             # Port utilities
    aria-snapshot.ts    # Accessibility snapshot capture
extension/
  background.js         # Cross-browser service worker (36 command handlers)
  manifest.json         # Extension manifest (MV3, Chrome + Firefox compatible)
  popup.html            # Extension popup UI
  popup.js              # Popup JavaScript
  icons/                # Extension icons

Credits

Browser MCP was adapted from the Playwright MCP server in order to automate the user's browser rather than creating new browser instances. This allows using the user's existing browser profile to use logged-in sessions and avoid bot detection mechanisms that commonly block automated browser use.