Package Exports

@rvegajr/browser-mcp-server
@rvegajr/browser-mcp-server/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@rvegajr/browser-mcp-server) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Browser MCP Server

WebSocket-based MCP Server for Browser MCP Chrome Extension

Version: 4.0.1

Overview

This is the Node.js MCP (Model Context Protocol) server that bridges IDEs (Claude Desktop, Cursor, Windsurf) to the Browser MCP Chrome Extension via WebSocket.

Architecture

IDE (stdin/stdout)
    ↕ MCP Protocol (newline-delimited JSON)
MCP Server (this)
    ↕ WebSocket (ws://localhost:8765)
Chrome Extension
    ↕ Chrome DevTools Protocol
Browser Tabs (DOM, Network, Console, etc.)

Installation

From NPM (recommended)

npm install -g @rvegajr/browser-mcp-server

From Source

cd mcp-server
npm install
npm link  # Makes 'browser-mcp-server' available globally

Usage

Start the server

browser-mcp-server

With custom port

browser-mcp-server --port 9000
# or
BROWSER_MCP_PORT=9000 browser-mcp-server

Configure your IDE

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "browser-mcp": {
      "command": "browser-mcp-server"
    }
  }
}

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "browser-mcp": {
      "command": "browser-mcp-server"
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "browser-mcp": {
      "command": "browser-mcp-server"
    }
  }
}

How It Works

IDE starts the server - When you start your IDE, it launches browser-mcp-server
Server waits for extension - Server starts and waits for Chrome Extension to connect
Extension connects via WebSocket - Chrome Extension connects to ws://localhost:8765
Bidirectional communication - Messages flow: IDE ↔ Server ↔ Extension

Features

✅ MCP Protocol - Full JSON-RPC 2.0 support
✅ Auto-reconnect - Handles extension reloads gracefully
✅ Message queueing - Queues messages when extension is offline
✅ Keepalive - Maintains WebSocket connection
✅ Cross-platform - Works on macOS, Linux, Windows

Components

index.js - Main server orchestration
stdio-handler.js - MCP protocol over stdin/stdout
websocket-client.js - WebSocket connection to extension
message-queue.js - Message queueing for offline handling

Troubleshooting

Extension not connected

Error:

Chrome Extension not connected. Make sure the extension is loaded.

Solution:

Load the Browser MCP extension in Chrome
Go to chrome://extensions/
Enable "Developer mode"
Click "Load unpacked"
Select the browser-mcp-extension folder

Port already in use