MCP Browser

MCP Browser

By neoforge-dev GitHub

NeoForge Browser MCP server - used to test the frontend

Overview

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.

how to use MCP Browser?

To use MCP Browser, clone the repository, set up the environment, and run the application either locally or via Docker.

key features of MCP Browser?

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

use cases of MCP Browser?

  1. Automating web interactions for testing purposes.
  2. Real-time data updates for AI applications.
  3. Facilitating browser-based automation tasks in a headless environment.

FAQ from MCP Browser?

  • What are the prerequisites for using MCP Browser?

You need Python 3.13+, Docker, and the uv dependency manager.

  • How can I run MCP Browser locally?

You can run it locally by following the setup instructions in the repository and executing the provided test scripts.

  • Is MCP Browser suitable for production use?

Yes, it can be deployed using Docker for production environments.

Content

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:

License

MIT

No tools information available.
No content found.