MCP Browser

🚀 MCP Browser

The headless browser interface for the Model Control Protocol (MCP). It offers a solution for automating browser interactions and integrating with AI agents, enabling real - time updates and event subscriptions.

✨ Features

• Achieve headless browser automation using Playwright.
• Provide a web UI for browser interaction.
• Support WebSocket communication for real - time updates.
• Offer a real - time browser event subscription system.
• Integrate MCP for AI agents.

📦 Installation

Prerequisites

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

One - line Installation

To install on a Mac with a single command:

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

This command downloads and runs the installer to avoid common issues.

Manual Installation

The steps for manual installation are as follows:

1. Clone the repository.
2. Run the installation script:

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

XQuartz Requirement

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

1. Check if XQuartz is installed and install it automatically if not.
2. Try to start the X11 server in multiple ways.
3. Prompt for manual startup if the automatic method fails. If you encounter issues, refer to the Resolving XQuartz Issues section.

💻 Usage Examples

Local Development

Setting up 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

Local Running

Simple test without Xvfb:

./simple_test.sh

Full test with Xvfb (requires X11):

./test_local.sh

Docker Deployment

Build and run using Docker Compose:

# Set the MCP secret key
export MCP_SECRET=your_secret_key

# Build and run
docker-compose up --build

Or use the provided script:

./run.sh

📚 Documentation

Configuration

The following environment variables can be set:

• MCP_SECRET: The key for MCP authentication.
• SERVER_PORT: The port on which the server runs (default: 7665).
• PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: Set to 1 to skip browser downloads and run in headless mode only.

API Endpoints

• GET /: Web UI.
• GET /api/status: Get the status of the browser and MCP client.
• WebSocket /ws: WebSocket endpoint for real - time communication.
• WebSocket /ws/browser/events: WebSocket endpoint for subscribing to browser events.
• 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 Subscription

The MCP browser supports real - time event subscription via WebSocket. This allows clients to receive browser events in real - time, including:

• Page events (navigation, loading, errors).
• DOM events (mutations, changes).
• Console events (logs, warnings, errors).
• Network events (requests, responses, errors). For detailed documentation on WebSocket events and the event subscription system, refer to:
• WebSocket Events Documentation
• Event Subscription Example

📄 License

MIT