# co-browser/browser-use-mcp-server architecture

> Architecture diagram of the GitHub repository co-browser/browser-use-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/co-browser/browser-use-mcp-server
- Repository: https://github.com/co-browser/browser-use-mcp-server

## Overview

##### Project type and purpose
- This is an open-source Python “MCP server” tool (browser-use-mcp-server) that exposes a Multi-Channel Protocol (MCP) interface to AI agents, translating MCP commands into browser automation tasks via the browser-use library and Playwright. It supports two transport protocols (SSE and stdio) and can stream the browser’s UI over VNC.

##### File structure
- Top-level files: configuration (Dockerfile, .env.example, CI/CD workflows, pyproject.toml, README, etc.)
- server/ folder: entry-point module (`__main__.py`) and a simple server implementation (`server.py`) for the “uv run server” command
- src/browser_use_mcp_server/: the installable package containing:
- cli.py – CLI command definitions (arguments, flags, modes)
- server.py – core MCP server logic, transport setup, task orchestration

##### Key insights from README
- Two transport modes:
- SSE mode: HTTP Server-Sent Events endpoint at `/sse` (port configurable)
- stdio mode: shell tool wrapper plus external mcp-proxy process (for stdin/stdout framing)
- Browser automation via Playwright (Chromium)
- VNC server for real-time UI streaming, with optional noVNC websocket proxy
- Utility of `uv` tool for build/install, but not a runtime dependency

##### Components & relationships
a. Main components
- AI Agent Client (e.g., Cursor, Windsurf, Claude)
- Transport Layer
- SSE HTTP server (Flask/FastAPI or custom async HTTP)
- stdio wrapper + external mcp-proxy process
- MCP Server Core (request dispatcher, async task manager)
- Browser-use library (command → Playwright bindings)
- Playwright Driver
- Chromium Browser Instance (headful/headless)
- VNC Server (e.g., Xvfb + TigerVNC)
- noVNC WebSocket Proxy (optional)
- Environment / Configuration (OPENAI_API_KEY, CHROME_PATH, PATIENT, .env)
b. Data flows & interactions
1. Client → Transport (SSE or stdio/mcp-proxy) → MCP Server Core
2. MCP Server Core → Browser-use CLI calls → Playwright driver → Chromium
3. Chromium UI → VNC Server → noVNC (WebSocket) → VNC Viewer client
4. Async task results / browser events → MCP Server Core → Transport → Client
c. Architectural patterns & principles
- Layered architecture (Transport → Application Core → Infrastructure)
- Async/await concurrency for parallel browser tasks
- Process orchestration (spawning mcp-proxy, VNC services)
d. Technologies & frameworks
- Python 3.x, Typer (CLI), asyncio
- browser-use library (abstraction over Playwright)
- Playwright (Chromium engine)
- mcp-proxy (external stdio transport helper)
- VNC (TigerVNC or similar) + noVNC

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External AI Clients
    subgraph "AI Agent Clients" 
        direction TB
        Clients["AI Agent Clients (Cursor, Windsurf, Claude)"]:::external
    end

    %% Transport Layer
    subgraph "Transport Layer" 
        direction TB
        SSE["SSE HTTP Server\n(/sse endpoint)"]:::transport
        Stdio["stdio Wrapper"]:::transport
        MCPProxy["mcp-proxy Process"]:::external
    end

    %% Core Logic
    subgraph "MCP Server Core" 
        direction TB
        CLI["CLI Definitions"]:::core
        MCPServerCore["MCP Server Core\n(dispatcher, tasks)"]:::core
        EntryPoint["uv run server\nEntry-point"]:::core
        SimpleServer["Simple Server Implementation"]:::core
    end

    %% Infrastructure
    subgraph "Infrastructure" 
        direction TB
        BrowserUse["browser-use Library"]:::infra
        Playwright["Playwright Driver"]:::infra
        Chromium["Chromium Browser"]:::infra
        VNCServer["VNC Server"]:::infra
        noVNC["noVNC WebSocket Proxy\n(optional)"]:::infra
    end

    %% Environment / Config
    subgraph "Environment & Config" 
        direction TB
        EnvExample[".env.example"]:::config
        Pyproject["pyproject.toml"]:::config
        DockerfileNode["Dockerfile"]:::config
    end

    %% External VNC Viewer
    subgraph "External Viewer"
        direction TB
        VNCViewer["VNC Viewer Client"]:::external
    end

    %% Connections
    Clients -->|"MCP request"| SSE
    Clients -->|"MCP request"| Stdio
    Stdio -->|"spawn"| MCPProxy
    SSE -->|"HTTP stream"| MCPServerCore
    Stdio -->|"Framed I/O"| MCPServerCore
    MCPServerCore -->|"invoke"| CLI
    CLI -->|"calls"| MCPServerCore
    MCPServerCore -->|"browser command"| BrowserUse
    BrowserUse -->|"Playwright API"| Playwright
    Playwright -->|"launch"| Chromium
    Chromium -->|"UI stream"| VNCServer
    VNCServer -->|"VNC stream"| noVNC
    noVNC -->|"WebSocket"| VNCViewer
    Chromium -->|"events/results"| MCPServerCore
    MCPServerCore -->|"stream results"| SSE
    MCPServerCore -->|"write output"| Stdio

    %% Environment boundaries
    EnvExample -.->|env vars| MCPServerCore
    Pyproject -.->|package config| CLI
    DockerfileNode -.->|container setup| Chromium
    DockerfileNode -.->|container setup| VNCServer

    %% Click Events
    click CLI "https://github.com/co-browser/browser-use-mcp-server/blob/main/src/browser_use_mcp_server/cli.py"
    click MCPServerCore "https://github.com/co-browser/browser-use-mcp-server/blob/main/src/browser_use_mcp_server/server.py"
    click EntryPoint "https://github.com/co-browser/browser-use-mcp-server/blob/main/server/__main__.py"
    click SimpleServer "https://github.com/co-browser/browser-use-mcp-server/blob/main/server/server.py"
    click Pyproject "https://github.com/co-browser/browser-use-mcp-server/blob/main/pyproject.toml"
    click EnvExample "https://github.com/co-browser/browser-use-mcp-server/blob/main/.env.example"
    click DockerfileNode "https://github.com/co-browser/browser-use-mcp-server/tree/main/Dockerfile"

    %% Styles
    classDef transport fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef core fill:#90EE90,stroke:#000,stroke-width:1px
    classDef infra fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef config fill:#F0F0F0,stroke:#000,stroke-width:1px
```
