DO
Web Scraping

Dockerized Playwright Chromium VNC MCP Server

Deploy a Dockerized Playwright Chromium VNC MCP server supporting stdio and resumable HTTP for co-browser automation and remote browsing.

View on GitHub
Quick Install
npx -y @co-browser/browser-use-mcp-server

Overview

This Dockerized Playwright Chromium VNC MCP server packages a Chromium browser (controlled via Playwright) together with a VNC display and an implementation of the Model Context Protocol (MCP). It exposes two primary transports for connecting clients: stdio (stdin/stdout) for direct programmatic control and a resumable HTTP transport that lets clients start, pause and resume long-running browsing sessions. The result is a reproducible, containerized runtime for co-browser automation, remote browsing, and AI-driven browser control.

For developers building scraping tools, AI agents, or interactive debugging workflows, the server provides a convenient, isolated browser runtime that can be orchestrated from other processes or remote machines. VNC access makes it simple to inspect pages visually and interact manually when needed, while the MCP transports support robust automated workflows that survive network interruptions.

Features

  • Chromium browser controlled by Playwright (headful or headless)
  • VNC display for remote visual access and manual interaction
  • MCP-compatible transports:
    • stdio (stdin/stdout) for direct process-to-process control
    • resumable HTTP for session persistence and interruption-tolerant workflows
  • Containerized as a single Docker image for reproducibility and easy deployment
  • Volume-backed session persistence to retain browser state across restarts
  • Configurable environment variables for ports, VNC password, and runtime flags
  • Useful for web scraping, remote debugging, UI automation, and AI-assisted browsing

Installation / Configuration

Clone the repository and build the image locally, or pull a prebuilt image if available.

Build locally:

git clone https://github.com/co-browser/browser-use-mcp-server.git
cd browser-use-mcp-server
docker build -t browser-use-mcp-server:latest .

Run the container (example):

docker run --rm \
  -p 8080:8080 \      # HTTP/protocol port (resumable HTTP transport)
  -p 5900:5900 \      # VNC port
  --shm-size=1g \     # recommended for Chromium stability
  -v $(pwd)/data:/data \  # persistent session data
  -e VNC_PASSWORD=secret \
  -e PLAYWRIGHT_HEADLESS=0 \
  --name mcp-server \
  browser-use-mcp-server:latest

Common environment variables (name examples — check the repository for exact names):

  • VNC_PASSWORD: password for VNC access
  • PLAYWRIGHT_HEADLESS: 0 or 1 to enable/disable headless mode
  • MCP_HTTP_PORT: port for resumable HTTP endpoint (default 8080)
  • RESUMABLE_HTTP_ENABLED: true/false to toggle the resumable transport

Docker Compose example:

version: "3.8"
services:
  mcp:
    image: browser-use-mcp-server:latest
    ports:
      - "8080:8080"
      - "5900:5900"
    environment:
      VNC_PASSWORD: "secret"
      PLAYWRIGHT_HEADLESS: "0"
    volumes:
      - ./data:/data
    shm_size: "1gb"

After starting the container, verify ports are open and consult the container logs to confirm the MCP server is ready.

Available Resources

  • Source and issues: https://github.com/co-browser/browser-use-mcp-server
  • Use a standard VNC client (TigerVNC, RealVNC, Remmina) to connect to port 5900
  • Use Playwright (Python/Node/.NET/Java) clients to drive Chromium from another environment if integrating with the server’s exposed endpoints
  • For resumable workflows, use HTTP clients that support chunked uploads/downloads and reconnect logic

Use Cases

  1. Web scraping with session persistence
    • Start a long-running scraping job in the MCP server
Tags:web-scraping