🚀 Browser MCP v4.0.12 - WebSocket Architecture

AI-Powered Browser Debugging Suite for Claude Desktop, Cursor, and Windsurf

🎯 What Is Browser MCP?

Browser MCP is a pure JavaScript Chrome extension that exposes complete browser state to AI assistants through the Model Context Protocol (MCP). It provides 33 powerful debugging tools for inspecting DOM, network, console, storage, and framework state - all accessible to Claude, Cursor, and Windsurf.

✨ Key Features

✅ WebSocket Architecture - Fast, reliable, bidirectional communication
✅ Pure JavaScript - No build step, no TypeScript compilation
✅ 33 Debugging Tools - DOM inspection, network monitoring, storage management
✅ Framework Detection - React, Vue, Angular, Svelte, and more
✅ Zero Dependencies - Self-contained Chrome extension
✅ One-Line Install - Automatic setup script
✅ Cross-Platform - macOS, Linux, Windows

📦 Quick Install

⚡ One-Command Installation

macOS / Linux:

# Interactive install
curl -fsSL https://raw.githubusercontent.com/YOLOVibeCode/browser-mcp/main/scripts/setup-mcp.sh | bash

# Auto-install (no prompts)
curl -fsSL https://raw.githubusercontent.com/YOLOVibeCode/browser-mcp/main/scripts/setup-mcp.sh | bash -s -- --yes

Windows (PowerShell):

# Interactive install
irm https://raw.githubusercontent.com/YOLOVibeCode/browser-mcp/main/scripts/setup-mcp.ps1 | iex

# Auto-install (no prompts)
(irm https://raw.githubusercontent.com/YOLOVibeCode/browser-mcp/main/scripts/setup-mcp.ps1) + ' -Yes' | iex

That's it! The script automatically:

✅ Checks & installs prerequisites (Node.js, npm, Git)
✅ Installs MCP server from NPM
✅ Configures your IDE (Claude/Cursor/Windsurf)
✅ Shows extension installation instructions

🎯 What You Need to Do

After running the install script:

Load the extension in Chrome:
- Open chrome://extensions/
- Enable "Developer mode"
- Click "Load unpacked"
- Select the folder shown by the script (copied to clipboard!)
Restart your IDE (Claude/Cursor/Windsurf)
Done! 🎉

🏗️ Architecture

WebSocket-Based Communication

┌──────────────────┐
│   IDE (Claude)   │  MCP Client
└────────┬─────────┘
         │ stdio (newline-delimited JSON)
         ↓
┌──────────────────┐
│  MCP Server      │  Node.js (browser-mcp-server)
│  (Node.js)       │  Translates MCP ↔ Extension
└────────┬─────────┘
         │ WebSocket (ws://localhost:8765)
         ↓
┌──────────────────┐
│ Chrome Extension │  Service Worker
│  - WebSocket     │  - Handles MCP requests
│    Server        │  - Routes to 33 tools
│  - MCP Protocol  │
│  - 33 Tools      │
└────────┬─────────┘
         │ Chrome DevTools Protocol
         ↓
┌──────────────────┐
│  Browser Tabs    │  DOM, Network, Console,
│                  │  Storage, Framework state
└──────────────────┘

Why WebSocket?

✅ Fast - <1ms communication overhead
✅ Reliable - Automatic reconnection
✅ Simple - Standard protocol
✅ Bidirectional - Real-time updates
✅ Cross-platform - Works everywhere

🛠️ Available Tools (33 Total)

DOM Inspection (8 tools)

getElementInfo - Get complete element details
querySelectors - jQuery-style DOM queries
getAccessibilityTree - ARIA/a11y inspection
getComputedStyles - Full CSS cascade
getElementPosition - Layout & positioning
getVisibilityInfo - Visibility detection
getDOMSnapshot - Complete DOM tree
getEventListeners - All event handlers

Network Monitoring (6 tools)

getNetworkRequests - All network activity
getRequestHeaders - HTTP headers
getResponseBody - Response content
getResourceTiming - Performance metrics
getWebSocketMessages - WebSocket traffic
clearNetworkCache - Cache management

Console & Debugging (5 tools)

getConsoleLogs - All console messages
evaluateExpression - Execute JavaScript
getErrorStack - Stack traces
getPerformanceMetrics - Core Web Vitals
getMemoryUsage - Memory profiling

Storage Management (5 tools)

getLocalStorage - localStorage inspection
getSessionStorage - sessionStorage inspection
getCookies - Cookie management
getIndexedDB - IndexedDB queries
clearStorage - Storage cleanup

Framework Detection (4 tools)

detectFramework - Identify framework
getComponentState - React/Vue state
getRenderChain - Component hierarchy
traceDataSources - Data flow tracking

Source Mapping (3 tools)

resolveSourceMap - Map deployed ↔ local code
getOriginalPosition - Source map lookup
listSourceFiles - Available source files

Tab Management (2 tools)

listActiveTabs - All browser tabs
switchToTab - Tab navigation

📁 Project Structure

browser-mcp/
│
├── mcp-server/                    # Node.js MCP Server
│   ├── index.js                   # Main server
│   ├── stdio-handler.js           # MCP protocol (stdin/stdout)
│   ├── websocket-client.js        # WebSocket connection
│   ├── message-queue.js           # Offline message queue
│   ├── package.json               # NPM package
│   └── README.md                  # Documentation
│
├── browser-mcp-extension/         # Chrome Extension
│   ├── background/
│   │   ├── service-worker.js      # Main entry point
│   │   ├── websocket-server.js    # WebSocket server
│   │   ├── websocket-frames.js    # RFC 6455 frame parser
│   │   ├── mcp-server.js          # MCP protocol handler
│   │   ├── tab-manager.js         # Tab state management
│   │   ├── adapters/
│   │   │   └── chrome-cdp.js      # Chrome DevTools Protocol
│   │   └── tools/                 # 33 debugging tools
│   │       ├── console-tools.js
│   │       ├── dom-tools.js
│   │       ├── network-tools.js
│   │       ├── storage-tools.js
│   │       ├── framework-tools.js
│   │       └── ... (11 total files)
│   │
│   ├── manifest.json              # Extension manifest
│   ├── icons/                     # Extension icons
│   └── popup/                     # Extension UI
│
├── scripts/
│   └── setup-mcp.sh               # One-line installer
│
├── package.json                   # Root package
└── README.md                      # This file

🎯 Usage Examples

Example 1: Inspect Element

Ask Claude/Cursor:

"Show me all properties of the submit button"

Browser MCP:

Uses getElementInfo tool
Returns: classes, IDs, attributes, computed styles, event listeners

Example 2: Debug Network Request

Ask Claude/Cursor:

"What API calls happened when I clicked that button?"

Browser MCP:

Uses getNetworkRequests tool
Returns: URL, method, status, headers, timing, response

Example 3: Find Component State

Ask Claude/Cursor:

"What's the current state of the UserProfile component?"

Browser MCP:

Uses detectFramework + getComponentState
Returns: props, state, hooks, context values

🔧 Manual Installation

Prerequisites

Node.js v16+ (with npm)
Git
Chrome or Chromium

Step 1: Install MCP Server

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

Step 2: Load Chrome Extension

Open Chrome and go to chrome://extensions/
Enable Developer mode (toggle in top-right)
Click Load unpacked
Select the browser-mcp-extension folder

Step 3: Configure Your IDE

Claude Desktop:

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

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

Cursor:

macOS/Linux: ~/.cursor/mcp.json
Windows: %USERPROFILE%\.cursor\mcp.json

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

Windsurf:

macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

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

Step 4: Restart Your IDE

Quit completely (Cmd+Q) and reopen.

🧪 Testing

Test MCP Server

# Start server
browser-mcp-server

# In another terminal, send test message
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | nc localhost 8765

Test in IDE

Open your IDE (Claude/Cursor/Windsurf)
Ask: "What MCP servers are available?"
Should see: "browser-mcp" with 33 tools
Try: "List all tabs in my browser"

🔧 Troubleshooting

Extension Not Loading

Check Chrome version (requires v90+)
Enable Developer mode in chrome://extensions/
Check console for errors in extension

MCP Server Not Connecting

Verify server is installed: which browser-mcp-server
Check if extension is loaded
Check WebSocket server started: Look for "WebSocket server started" in extension console
Check port 8765 is not in use: lsof -i :8765

IDE Not Detecting MCP Server

Verify config file location
Restart IDE completely (Cmd+Q, then reopen)
Check IDE logs for MCP errors
Verify browser-mcp-server is in PATH

📚 Documentation

MCP Server: mcp-server/README.md
Extension: browser-mcp-extension/README.md
Tools List: browser-mcp-extension/ALL_33_TOOLS_COMPLETE.md

🆕 What's New in v4.0.0

🎉 Complete Architecture Rewrite

✅ WebSocket-based - Replaced Chrome Native Messaging with WebSocket
✅ Faster - <1ms communication overhead (vs ~50ms with Native Messaging)
✅ More Reliable - Auto-reconnect, message queueing
✅ Simpler - No manifest files, no Chrome-specific setup
✅ Better DX - Easier to test and debug

🔥 Breaking Changes

browser-mcp-native-host → browser-mcp-server (new NPM package)
No more native messaging manifests required
Extension now requires sockets permission instead of nativeMessaging

📦 Migration from v3.x

# Uninstall old package
npm uninstall -g browser-mcp-native-host

# Install new package
npm install -g @rvegajr/browser-mcp-server

# Update IDE config - change command name:
# OLD: "command": "browser-mcp-host"
# NEW: "command": "browser-mcp-server"

# Reload extension in Chrome

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Add tests for new features
Submit a pull request

📄 License

MIT License - see LICENSE

🌟 Why Browser MCP?

Pure JavaScript - No build step, instant development
Chrome Native - Uses official Chrome DevTools Protocol
MCP Compatible - Works with Claude, Cursor, Windsurf
Self-Contained - No external dependencies
Production Ready - Fully tested with 33 tools
WebSocket Fast - Modern, efficient communication

Made with ❤️ by YOLOVibeCode

⭐ Star this repo if it helps your debugging workflow!

🔗 Links

GitHub: https://github.com/YOLOVibeCode/browser-mcp
NPM Package: https://www.npmjs.com/package/@rvegajr/browser-mcp-server
Issues: https://github.com/YOLOVibeCode/browser-mcp/issues
MCP Protocol: https://modelcontextprotocol.io

Name		Name	Last commit message	Last commit date
Latest commit History 67 Commits
.unvibe/backups		.unvibe/backups
browser-mcp-extension		browser-mcp-extension
documents		documents
mcp-server		mcp-server
releases		releases
scripts		scripts
src		src
test-results		test-results
tests		tests
.cursorrules		.cursorrules
.gitignore		.gitignore
ARCHITECTURE_TEST_SPECIFICATION.md		ARCHITECTURE_TEST_SPECIFICATION.md
AUTOMATED_AI_TESTING.md		AUTOMATED_AI_TESTING.md
E2E_TEST_RESULTS.md		E2E_TEST_RESULTS.md
ENGINEER_IMPLEMENTATION_SUMMARY.md		ENGINEER_IMPLEMENTATION_SUMMARY.md
LICENSE		LICENSE
README.md		README.md
TEST_IMPLEMENTATION_COMPLETE.md		TEST_IMPLEMENTATION_COMPLETE.md
package.json		package.json
run-comprehensive-tests.sh		run-comprehensive-tests.sh
test-e2e-full.cjs		test-e2e-full.cjs

License

YOLOVibeCode/browser-mcp

Folders and files

Latest commit

History

Repository files navigation

🚀 Browser MCP v4.0.12 - WebSocket Architecture

🎯 What Is Browser MCP?

✨ Key Features

📦 Quick Install

⚡ One-Command Installation

🎯 What You Need to Do

🏗️ Architecture

WebSocket-Based Communication

Why WebSocket?

🛠️ Available Tools (33 Total)

DOM Inspection (8 tools)

Network Monitoring (6 tools)

Console & Debugging (5 tools)

Storage Management (5 tools)

Framework Detection (4 tools)

Source Mapping (3 tools)

Tab Management (2 tools)

📁 Project Structure

🎯 Usage Examples

Example 1: Inspect Element

Example 2: Debug Network Request

Example 3: Find Component State

🔧 Manual Installation

Prerequisites

Step 1: Install MCP Server

Step 2: Load Chrome Extension

Step 3: Configure Your IDE

Step 4: Restart Your IDE

🧪 Testing

Test MCP Server

Test in IDE

🔧 Troubleshooting

Extension Not Loading

MCP Server Not Connecting

IDE Not Detecting MCP Server

📚 Documentation

🆕 What's New in v4.0.0

🎉 Complete Architecture Rewrite

🔥 Breaking Changes

📦 Migration from v3.x

🤝 Contributing

📄 License

🌟 Why Browser MCP?

🔗 Links

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Contributors 2

Uh oh!

Languages

Packages