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

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

3. Configure Claude Code

Add the MCP server to your Claude Code configuration:

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:

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

Developer Tools

Browser Management

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:

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:

Connection failures:

Server Issues

Server won't start:

MCP connection fails:

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

Server Development

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:

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