What is Mcp Browser

mcp-browser is a headless browser interface designed for the Model Control Protocol (MCP), enabling automated browser interactions and real-time updates.

Use cases

Use cases include automated testing of web applications, real-time monitoring of browser events, integration with AI systems for intelligent web interactions, and providing a user-friendly interface for browser automation.

How to use

To use mcp-browser, clone the repository, set up a virtual environment with uv, install dependencies, and run the server locally or via Docker. Configuration involves setting environment variables like MCP_SECRET and SERVER_PORT.

Key features

Key features include headless browser automation using Playwright, a web UI for interaction, WebSocket communication for real-time updates, a subscription system for browser events, and integration with MCP for AI agents.

Where to use

mcp-browser can be utilized in web development, automated testing, AI agent interactions, and any scenario requiring real-time browser event handling.

MCP Browser

A headless browser interface for the Model Control Protocol (MCP).

Features

• Headless browser automation using Playwright
• Web UI for browser interaction
• WebSocket communication for real-time updates
• Real-time browser event subscription system
• Integration with MCP for AI agents

Prerequisites

• Python 3.13+
• uv for dependency management
• Docker (for containerized usage)

Installation

One-Line Installation

To install MCP Browser on your Mac with one command:

curl -sSL https://raw.githubusercontent.com/neoforge-dev/mcp-browser/main/install_one_line.sh | bash

This command will download and run the installer with proper line ending handling to avoid common issues.

Manual Installation

For manual installation:

1. Clone this repository
2. Run the installer script:

git clone https://github.com/neoforge-dev/mcp-browser.git
cd mcp-browser
./install.sh

XQuartz Requirements

MCP Browser requires XQuartz (X11) for proper visualization. The installer will:

1. Check if XQuartz is already installed and install it if needed
2. Attempt to start the X11 server in various ways
3. Prompt you to start it manually if automatic methods fail

If you encounter issues, see the Troubleshooting XQuartz Issues section.

Local Development

Setup with uv

# Clone the repository
git clone https://github.com/yourusername/mcp-browser.git
cd mcp-browser

# Install dependencies
uv venv .venv
source .venv/bin/activate
uv pip install -e .

# Install Playwright browsers
python -m playwright install

Running Locally

For a simple test without Xvfb:

./simple_test.sh

For a full test with Xvfb (requires X11):

./test_local.sh

Docker Deployment

Build and run using Docker Compose:

# Set your MCP secret
export MCP_SECRET=your_secret_key

# Build and run
docker-compose up --build

Or use the provided script:

./run.sh

Configuration

The following environment variables can be set:

• MCP_SECRET: Secret key for MCP authentication
• SERVER_PORT: Port to run the server on (default: 7665)
• PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: Set to 1 to skip browser download and run in headless-only mode

API Endpoints

• GET /: Web UI
• GET /api/status: Get browser and MCP client status
• WebSocket /ws: WebSocket endpoint for real-time communication
• WebSocket /ws/browser/events: WebSocket endpoint for browser event subscriptions
• GET /api/browser/subscribe: Subscribe to browser events
• GET /api/browser/unsubscribe: Unsubscribe from browser events
• GET /api/browser/subscriptions: List active event subscriptions

Event Subscriptions

The MCP Browser supports real-time event subscriptions via WebSockets. This allows clients to receive browser events as they happen, including:

• Page events (navigation, load, error)
• DOM events (mutations, changes)
• Console events (logs, warnings, errors)
• Network events (requests, responses, errors)

For detailed documentation and examples of the event subscription system, see:

• WebSocket Events Documentation
• Event Subscription Example

License

MIT