# saik0s/mcp-browser-use architecture

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

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

## Overview

##### Project Type and Purpose
- This is a specialized automation server focused on browser automation via MCP.
- It integrates multiple LLM providers (e.g., Anthropic, OpenAI, Azure, etc.) to drive browser interactions, making it both a server and a middleware layer for natural language-driven browser control.
- The system extends the browser-use/web-ui framework and adapts its core automation and configuration patterns.

##### File Structure
- The primary source code is located under the “src/mcp_server_browser_use” package.
- Key directories include:
- agent: Contains files such as custom_agent.py, custom_massage_manager.py, custom_prompts.py, and custom_views.py. This module likely handles AI agent behaviors, prompts, and managing messages exchanged between the AI and browser automation routines.
- browser: Includes custom_browser.py and custom_context.py. This module is responsible for direct browser interactions (navigating pages, form filling, element interactions, etc.) and managing context for browser sessions.
- controller: Contains custom_controller.py. This module likely orchestrates interactions between the agents and the browser interface and maintains overall flow and logic.
- utils: Holds helper functions and modules like agent_state.py, deep_research.py, llm.py, and general utilities. These support tasks like state management, integrations with different LLM providers, and common functionality.
- The top-level server file (server.py) serves as the entry point for running the MCP server.
- Other files (e.g., pyproject.toml, LICENSE, README.md) and configuration hints (e.g., uv.lock, .python-version) indicate standard packaging and deployment practices.

##### Core Components
a. Entry Point & Orchestration:
- Server (src/mcp_server_browser_use/server.py): Main entry point that bootstraps the server.
- Controller (src/mcp_server_browser_use/controller/custom_controller.py): Manages overall application flow.
b. Domain Modules:
- Agent Modules (inside “agent” folder): Handle AI agent logic, custom prompts, and message management.
- Browser Modules (inside “browser” folder): Implement browser automation logic and context management.
- Utilities (inside “utils” folder): Provide support functions such as state management, deep research algorithms, and LLM integration.
c. External Dependencies & Configuration:
- LLM Providers: Use environment variables (as detailed in the README) to support Anthropic, OpenAI, Azure, etc.
- Browser/Automation: Integration with Chrome/Chromium settings, headless options, and browser interaction configurations.
- Supporting frameworks/libraries: uv (for command execution/fast packaging) and any underlying frameworks inherited from browser-use/web-ui.

##### Establishing Relationships and Interactions
– Within it, a “Controller” that coordinates between domain modules.
- Directional flows:

##### Architectural Patterns and Design Principles
- Separation of Concerns: The design separates agent logic, browser management, and orchestration (controller), each with its domain responsibilities.
- Modular Architecture: By placing related functionalities in dedicated modules (agent, browser, controller, utils), the design allows for extensibility and maintenance.
- Configurability: The system leverages environment variables to interact with multiple external LLM providers, making the architecture flexible and adaptable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Internal Components"
        S["Server (Entry Point)"]:::internal
        C["Controller"]:::internal
        A["Agent Module"]:::internal
        B["Browser Module"]:::internal
        U["Utils"]:::internal
    end
    E["LLM Providers & Browser Environment"]:::external

    S -->|"bootstraps"| C
    C -->|"delegates"| A
    C -->|"orchestrates"| B
    A -.->|"uses"| U
    B -.->|"uses"| U

    S -.->|"configures"| E
    C -.->|"accesses"| E
    A -.->|"integrates"| E
    B -.->|"integrates"| E

    click S "https://github.com/saik0s/mcp-browser-use/blob/main/src/mcp_server_browser_use/server.py"
    click C "https://github.com/saik0s/mcp-browser-use/blob/main/src/mcp_server_browser_use/controller/custom_controller.py"
    click A "https://github.com/saik0s/mcp-browser-use/tree/main/src/mcp_server_browser_use/agent"
    click B "https://github.com/saik0s/mcp-browser-use/tree/main/src/mcp_server_browser_use/browser"
    click U "https://github.com/saik0s/mcp-browser-use/tree/main/src/mcp_server_browser_use/utils"

    classDef internal fill:#AEE1F9,stroke:#333,stroke-width:2px
    classDef external fill:#FFEE93,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5
```
