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)

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