robhicks/browser-mcp-bridge

Browser MCP Bridge

A comprehensive browser extension and MCP server solution that bridges browser content, developer tools data, and web page interactions with Claude Code through the Model Context Protocol (MCP).

Overview

This project consists of two main components:

1. Browser Extension - Captures browser content, DOM data, console messages, network activity, and developer tools information
2. MCP Server - Exposes browser data to Claude Code through standardized MCP tools and resources

Features

Browser Extension

• Page Content Extraction - Full HTML, text content, metadata, and page structure
• DOM Inspection - Complete DOM tree snapshots with computed styles
• Console Monitoring - Real-time console logs, errors, and warnings
• Network Activity - HTTP requests, responses, and performance metrics
• Developer Tools Integration - Custom DevTools panel for advanced inspection
• JavaScript Execution - Execute arbitrary JavaScript in page context
• Screenshot Capture - Visual snapshots of browser tabs
• Accessibility Data - Accessibility tree and ARIA attributes
• Performance Metrics - Load times, resource usage, and Core Web Vitals

MCP Server

• 11 Specialized Tools - Comprehensive browser automation and inspection tools
• Dynamic Resources - Real-time access to page content, DOM, and console data
• WebSocket Communication - Real-time bidirectional communication with browser
• Multi-tab Support - Manage and inspect multiple browser tabs simultaneously

Installation

Prerequisites

• Node.js 18.0.0 or higher
• Chrome, Edge, or Chromium-based browser
• Claude Code CLI

1. Install the MCP Server

# Clone or navigate to the project directory
cd /path/to/browser-mcp

# Install server dependencies
cd server
npm install

# Make the server executable
chmod +x index.js

2. Install the Browser Extension

Chrome/Chromium/Edge Installation

1. Open Extension Management

   • Navigate to chrome://extensions/ (Chrome)
   • Or edge://extensions/ (Edge)

2. Enable Developer Mode

   • Toggle "Developer mode" in the top-right corner

3. Load the Extension

   • Click "Load unpacked"
   • Select the /path/to/browser-mcp/extension directory
   • The extension should appear in your extensions list

4. Verify Installation

   • Look for the "Browser MCP Bridge" extension icon in your toolbar
   • The extension should show as "Enabled"

Alternative: Create Extension Package

# Navigate to extension directory
cd extension

# Create a zip package for distribution
zip -r browser-mcp-extension.zip . -x "*.DS_Store" "node_modules/*"

3. Configure Claude Code

Add the MCP server to your Claude Code configuration:

{
  "mcpServers": {
    "browser-mcp": {
      "command": "node",
      "args": ["/path/to/browser-mcp/server/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

macOS/Linux: Edit ~/.config/claude-desktop/claude_desktop_config.json

Windows: Edit %APPDATA%/Claude/claude_desktop_config.json

Usage

1. Start the MCP Server

The server starts automatically when Claude Code launches, or manually:

cd server
npm start

The server will:

• Listen on port 3000 for WebSocket connections
• Provide health check endpoint at http://localhost:3000/health
• Connect to Claude Code via stdio

2. Connect Browser Extension

1. Open the Extension Popup

   • Click the Browser MCP Bridge icon in your toolbar

2. Configure Connection

   • Server URL should default to ws://localhost:3000/mcp
   • Click "Connect to Server"
   • Status should change to "Connected"

3. Verify Connection

   • Green status indicator shows successful connection
   • Extension will automatically reconnect if disconnected

3. Use Claude Code Tools

Once connected, Claude Code has access to these tools:

Page Inspection Tools

# Get complete page content and metadata
get_page_content

# Get structured DOM snapshot
get_dom_snapshot

# Execute JavaScript in page context
execute_javascript --code "document.title"

# Capture screenshot
capture_screenshot

Developer Tools

# Get console messages
get_console_messages

# Get network requests
get_network_requests

# Get performance metrics
get_performance_metrics

# Get accessibility tree
get_accessibility_tree

Browser Management

# List all open tabs
get_browser_tabs

# Attach debugger for advanced inspection
attach_debugger --tabId 123

# Detach debugger
detach_debugger --tabId 123

4. DevTools Panel

1. Open Chrome DevTools

   • Right-click on any page → "Inspect"
   • Or press F12

2. Find MCP Bridge Panel

   • Look for "MCP Bridge" tab alongside Console, Network, etc.
   • Click to open the custom panel

3. Use Panel Features

   • Quick capture buttons for different data types
   • Real-time connection status
   • Message logging and debugging
   • Visual data display

Example Workflows

Web Development Debugging

1. Inspect Page Issues

   # In Claude Code
   "Analyze this page for accessibility issues"
   # Uses get_accessibility_tree and get_page_content
   

2. Performance Analysis

   "Check this page's performance metrics and suggest optimizations"
   # Uses get_performance_metrics and get_network_requests
   

3. Console Error Analysis

   "Review the console errors and help me fix them"
   # Uses get_console_messages
   

Automated Testing Support

1. Form Testing

   execute_javascript --code "
     const form = document.querySelector('form');
     const inputs = form.querySelectorAll('input');
     return Array.from(inputs).map(i => ({name: i.name, type: i.type}));
   "
   

2. Visual Regression

   capture_screenshot
   # Compare with baseline screenshots
   

Content Analysis

1. SEO Analysis

   get_page_content --includeMetadata true
   # Analyze meta tags, headings, content structure
   

2. Content Extraction

   execute_javascript --code "
     return Array.from(document.querySelectorAll('article')).map(a => a.innerText);
   "
   

Configuration

Extension Settings

The extension popup allows you to:

• Change WebSocket server URL
• View connection statistics
• Manually trigger data capture
• Access DevTools panel

Server Configuration

Environment variables:

# WebSocket port (default: 3000)
PORT=3000

# Enable debug logging
DEBUG=true

# Maximum message size (bytes)
MAX_MESSAGE_SIZE=10485760

Security Considerations

• Local Connection Only - Server only accepts connections from localhost
• Same-Origin Policy - Extension respects browser security policies
• No Password Storage - No sensitive data is stored or transmitted
• Minimal Permissions - Extension requests only necessary permissions

Troubleshooting

Extension Issues

Extension not loading:

# Check browser console for errors
# Verify all files are present in extension directory
# Ensure manifest.json is valid

Connection failures:

# Verify MCP server is running on port 3000
# Check WebSocket URL in extension popup
# Look for firewall blocking localhost:3000

Server Issues

Server won't start:

# Check Node.js version (18.0.0+)
npm list  # Verify dependencies installed
node --version

MCP connection fails:

# Verify Claude Code configuration
# Check server logs for errors
# Ensure stdio communication is working

Common Fixes

1. Restart Everything

   # Stop Claude Code
   # Kill server process
   # Disable/re-enable extension
   # Restart browser
   # Start server and Claude Code
   

2. Clear Extension Storage

   # In Chrome: chrome://extensions/
   # Find extension → Details → Extension options
   # Clear stored data
   

3. Reset Server Connection

   cd server
   npm run dev  # Use with --watch for debugging
   

Development

Extension Development

cd extension

# Watch for changes (if using build tools)
npm run dev

# Test in browser
# Make changes and reload extension

Server Development

cd server

# Development mode with auto-restart
npm run dev

# Debug mode with verbose logging
DEBUG=* npm start

Adding New Tools

1. Add tool definition to server ListToolsRequestSchema handler
2. Implement tool logic in server CallToolRequestSchema handler
3. Add browser-side handler in extension background.js
4. Test with Claude Code

API Reference

MCP Tools

WebSocket Messages

The extension communicates with the server using structured WebSocket messages:

// Page content data
{
  type: "browser-data",
  source: "content-script",
  tabId: 123,
  url: "https://example.com",
  data: { /* page content */ }
}

// Tool responses
{
  type: "response",
  action: "getPageContent",
  tabId: 123,
  data: { /* response data */ }
}

// Error messages
{
  type: "error",
  action: "getPageContent",
  tabId: 123,
  error: "Error message"
}

License

MIT License - See LICENSE file for details.

Contributing

1. Fork the repository
2. Create feature branch
3. Make changes with tests
4. Submit pull request

Support

For issues and questions:

• Check troubleshooting section above
• Review browser console and server logs
• Create GitHub issue with detailed information