How co-browser/browser-use-mcp-server works
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