How saik0s/mcp-browser-use works
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.