MCP Browser

A professional Model Context Protocol (MCP) server that provides comprehensive browser automation and console log capture through Chrome extension integration. Features automated installation, DOM interaction capabilities, and seamless Claude Code integration.

🌟 Zero Documentation Required

Get started without reading any documentation:

pip install mcp-browser
mcp-browser extension install
mcp-browser install
mcp-browser start --background

Load the extension in Chrome (one-time):

• chrome://extensions → enable Developer mode → “Load unpacked” → select ~/mcp-browser-extensions/chrome/

Prefer an interactive wizard?

mcp-browser quickstart

Need help anytime? The CLI is completely self-documenting:

mcp-browser --help          # See all commands
mcp-browser reference       # Quick reference card
mcp-browser doctor          # Diagnose and fix issues
mcp-browser tutorial        # Step-by-step feature tour

🚀 Quick Start (30 Seconds)

Option 1: Zero-Config Installation (Recommended)

pip install mcp-browser
mcp-browser extension install
mcp-browser install
mcp-browser start --background

Option 2: Development Installation

git clone https://github.com/browserpymcp/mcp-browser.git
cd mcp-browser
make install
make ext-deploy
mcp-browser start --background

Next: load the extension

• Chrome: chrome://extensions → “Load unpacked” → ./mcp-browser-extensions/chrome/

✨ Features

Core Capabilities

• 🎯 Advanced DOM Interaction: Click elements, fill forms, submit data, select dropdowns, wait for elements
• 📊 Console Log Capture: Real-time capture from all browser tabs with advanced filtering
• 📷 Screenshots: Extension-backed viewport capture
• 🌐 Smart Navigation: Programmatic browser navigation with URL validation
• 🔄 Auto-Discovery: Dynamic port allocation (default 8851-8899) with collision avoidance
• 🤖 AI-Ready: 5 consolidated MCP tools optimized for efficient prompting

Technical Architecture

• ⚡ Service-Oriented Architecture (SOA): Clean separation with dependency injection
• 🔗 WebSocket Communication: Real-time bidirectional browser communication
• 💾 JSONL Storage: Automatic log rotation (50MB) with 7-day retention
• 🎨 Chrome Extension: Visual connection status with real-time monitoring
• 🤖 MCP Integration: Consolidated tool surface for AI-driven browser automation

Installation & CLI

• 📦 PyPI Distribution: pip install mcp-browser for instant setup
• 🎯 Interactive Setup: mcp-browser quickstart for guided configuration
• 🔧 Self-Documenting CLI: Built-in help, tutorials, and troubleshooting
• 🏥 Health Monitoring: mcp-browser doctor for system diagnostics
• ⚙️ Smart Configuration: Auto-generated settings with sensible defaults
• 🧪 Self-Verification: Built-in installation testing and demo capabilities

Architecture

The project follows a Service-Oriented Architecture (SOA) with dependency injection:

• WebSocket Service: Handles browser connections with port auto-discovery
• Storage Service: Manages JSONL log files with rotation
• Browser Service: Processes console messages and manages browser state
• DOM Interaction: DOM actions, extraction, and screenshots via extension protocol
• MCP Service: Exposes tools to MCP clients (Claude Code/Desktop, etc.)

📦 Installation

Platform Support

Supported:

• macOS (recommended - full AppleScript integration)
• Linux (Chrome/Chromium/Firefox support)

Not Supported:

• Windows (incompatible due to AppleScript dependencies)

Prerequisites

• Python 3.10+ (with pip)
• Chrome/Chromium browser
• macOS or Linux operating system

Method 1: PyPI Installation (Recommended)

pip install mcp-browser
mcp-browser extension install
mcp-browser install
mcp-browser start --background

Method 2: Development Installation

git clone https://github.com/browserpymcp/mcp-browser.git
cd mcp-browser
make install
make ext-deploy
mcp-browser start --background

Method 3: pipx Installation (Isolated)

# Install with pipx for complete isolation
pipx install mcp-browser
mcp-browser extension install
mcp-browser install
mcp-browser start --background

Prefer an interactive wizard? Run mcp-browser quickstart.

Need detailed installation help? See INSTALLATION.md for platform-specific instructions, troubleshooting, and alternative methods.

🎯 Usage

Self-Documenting CLI

New to MCP Browser? The CLI guides you through everything:

# Interactive setup and feature tour
mcp-browser quickstart     # Complete setup guide
mcp-browser tutorial       # Step-by-step feature demo
mcp-browser doctor         # Diagnose and fix issues

# Get help anytime
mcp-browser --help         # See all commands
mcp-browser start --help   # Help for specific commands

Professional Server Management

# Server control
mcp-browser start --background  # Start daemon in background (recommended)
mcp-browser start               # Start in foreground (debugging)
mcp-browser stop                # Stop daemon for current project
mcp-browser status              # Status for current project

# Installation management
mcp-browser install              # Install/configure MCP integration
mcp-browser uninstall            # Remove MCP config entry

# MCP integration
mcp-browser mcp                 # Run in MCP stdio mode (invoked by MCP clients)

# Utilities
mcp-browser version        # Show version info

# Extension management
mcp-browser extension install [--local]
mcp-browser extension update [--local]
mcp-browser extension path --check

# Local testing (CLI)
mcp-browser browser logs --limit 20
mcp-browser browser extract content

Uninstalling MCP Browser

MCP Browser provides flexible uninstall options from simple MCP config removal to complete cleanup.

Quick Uninstall (MCP Config Only)

# Remove from Claude Code (default)
mcp-browser uninstall

# Remove from Claude Desktop
mcp-browser uninstall --target claude-desktop

# Remove from both
mcp-browser uninstall --target both

Complete Cleanup

# Preview what would be removed (recommended first step)
mcp-browser uninstall --clean-all --dry-run

# Remove everything with confirmation
mcp-browser uninstall --clean-all

# Remove everything without confirmation (use with caution)
mcp-browser uninstall --clean-all --yes

Cleanup Options

Flag	Description	What Gets Removed
--clean-local	Clean project files	./mcp-browser-extensions/, ./mcp-browser-extension/ (legacy), ./.mcp-browser/
--clean-global	Clean user data	~/.mcp-browser/ (data, logs, config)
--clean-all	Complete removal	MCP config + local + global data (add --playwright for caches)
--playwright	Remove Playwright cache	~/.cache/ms-playwright/ (or OS equivalent; optional)
--backup / --no-backup	Control backup creation	Creates timestamped backup (default: enabled)
--dry-run	Preview changes	Shows what would be removed without doing it
-y, --yes	Skip confirmations	Removes without prompting (dangerous)

Safety Features

• Automatic Backups: By default, creates timestamped backups in ~/.mcp-browser-backups/ before removing data
• Confirmation Prompts: Asks for confirmation before destructive operations (unless --yes is used)
• Preview Mode: Use --dry-run to see exactly what would be removed
• Selective Cleanup: Choose specific cleanup levels based on your needs

Example Scenarios

# Scenario 1: Remove MCP config only (safest)
mcp-browser uninstall

# Scenario 2: Clean local project files only
mcp-browser uninstall --clean-local

# Scenario 3: Clean global data with backup
mcp-browser uninstall --clean-global

# Scenario 4: Preview complete removal
mcp-browser uninstall --clean-all --dry-run

# Scenario 5: Complete removal with backup
mcp-browser uninstall --clean-all

# Scenario 6: Nuclear option (no backup, no confirmation)
mcp-browser uninstall --clean-all --no-backup --yes

For detailed uninstall instructions and recovery options, see UNINSTALL.md

Uninstall the Package Itself

After removing configurations and data, uninstall the package:

# If installed with pip
pip uninstall mcp-browser

# If installed with pipx
pipx uninstall mcp-browser

🛠️ MCP Tools (MCP surface)

MCP Browser exposes a consolidated tool surface optimized for AI assistants:

• browser_action — navigate/click/fill/select/wait
• browser_query — logs/element/capabilities
• browser_screenshot — extension-backed screenshot capture
• browser_form — fill/submit forms
• browser_extract — readable content or semantic DOM extraction

Tool schemas, examples, and legacy-name mapping: docs/reference/MCP_TOOLS.md.

Chrome Extension Features

The Chrome extension provides comprehensive browser integration:

Automatic Console Capture

• Multi-tab monitoring: Captures console logs from all active browser tabs
• Real-time buffering: Collects messages every 2.5 seconds for optimal performance
• Level filtering: Supports error, warn, info, and debug message types
• Automatic initialization: Self-starts on page load with verification message

Visual Connection Management

• Status indicator: Toolbar icon shows connection state (green = connected, red = disconnected)
• Port display: Shows active WebSocket port in extension popup
• Auto-reconnection: Automatically reconnects on connection loss
• Connection diagnostics: Real-time connection health monitoring

DOM Interaction Support

• Element discovery: Supports CSS selectors, XPath, and text-based element finding
• Form automation: Integrates with form filling and submission tools
• Event handling: Manages click, input, and selection events
• Wait mechanics: Handles dynamic content and AJAX loading

Safari Extension (macOS)

Full Safari support with native macOS app wrapper:

Installation

# Automated conversion from Chrome extension
cd /path/to/mcp-browser
bash scripts/create-safari-extension.sh

Features

• Safari 17+ Support: Full Manifest V3 compatibility with service workers
• Cross-browser API: Uses both chrome.* and browser.* namespaces
• Native App Wrapper: Packaged as macOS application for App Store distribution
• Code Signing Ready: Configured for both development and distribution signing
• Xcode Project: Automatically generated with proper capabilities

Key Differences from Chrome

• Requires macOS app wrapper (automatically created)
• Uses Apple's safari-web-extension-converter tool
• Needs App Sandbox capabilities for WebSocket connections
• Distribution requires Apple Developer account for signing

📚 Complete Guide: See docs/guides/SAFARI_EXTENSION.md for:

• Step-by-step setup instructions
• Xcode project configuration
• Code signing and notarization
• App Store and direct distribution
• Testing and debugging guides
• Common issues and solutions

🗂️ File Structure

Repository structure

mcp-browser/
├── src/                      # Python package (mcp_browser)
│   ├── cli/                  # CLI commands and utilities
│   ├── services/             # SOA services (WebSocket, MCP, storage, DOM, etc.)
│   ├── extension/            # Packaged Chrome extension assets (used by CLI installer)
│   └── extensions/           # Unpacked extension sources (chrome/firefox/safari)
├── docs/                     # Documentation (start at docs/README.md)
├── scripts/                  # Dev + release scripts
├── tests/                    # Tests
└── mcp-browser-extensions/   # Generated unpacked extensions (gitignored)

Runtime data

~/.mcp-browser/
├── config/settings.json      # Configuration
├── data/<port>/console.jsonl # Stored console logs (JSONL, rotated)
├── logs/mcp-browser.log      # Main log
└── server.pid                # Daemon registry (per-project entries)

Development

Single-Path Workflows

This project follows the "ONE way to do ANYTHING" principle. Use these commands:

# ONE way to install
make install

# ONE way to develop
make dev

# ONE way to test
make test

# ONE way to build
make build

# ONE way to format code
make lint-fix

# See all available commands
make help

Local smoke test

make ext-deploy
mcp-browser start --background
mcp-browser demo

Running Tests

# Run all tests with coverage
make test

# Run specific test types
make test-unit
make test-integration
make test-extension

Configuration

Default config file:

• ~/.mcp-browser/config/settings.json

Use a custom config for a single invocation:

mcp-browser --config /path/to/settings.json start --background

Full details: docs/guides/INSTALLATION.md.

Troubleshooting

Start with:

mcp-browser doctor

Maintained guide: docs/guides/TROUBLESHOOTING.md.

License

MIT License - see LICENSE file for details

Documentation

Start here:

• docs/README.md (doc index)
• docs/guides/INSTALLATION.md (install + first run)
• docs/reference/MCP_TOOLS.md (authoritative MCP tool surface)
• docs/reference/CODE_STRUCTURE.md (architecture overview)
• docs/developer/DEVELOPER.md (maintainer guide)

Project-wide doc standards: docs/STANDARDS.md.

AI agent instructions: CLAUDE.md.

Contributing

Contributions are welcome! Please follow the single-path development workflow:

1. Setup: make setup (installs deps + pre-commit hooks)
2. Develop: make dev (start development server)
3. Quality: make quality (run all linting and tests)
4. Submit: Create feature branch and submit pull request

All code must pass make quality before submission. The pre-commit hooks will automatically format and lint your code.

Support

For issues and questions:

• GitHub Issues: https://github.com/browserpymcp/mcp-browser/issues
• Documentation: Start with docs/README.md
• Architecture Questions: See docs/reference/CODE_STRUCTURE.md