Unleashing AI Agents: browser-use-mcp-server - Your Bridge to Web Automation via the Model Context Protocol

Overview

browser-use-mcp-server is a critical component for developers seeking to integrate Large Language Models (LLMs) with real-world web environments. By leveraging the Model Context Protocol (MCP), this server provides a standardized interface for AI agents to control web browsers, enabling sophisticated automation tasks, data extraction, and interactive experiences. It acts as a crucial intermediary, translating high-level AI commands into precise browser actions.

Core Requirements

Before diving in, ensure you have the following foundational tools installed:

• uv: A blazing-fast Python package manager, significantly accelerating dependency resolution and installation.
• Playwright: A reliable browser automation framework supporting Chromium, Firefox, and WebKit.
• mcp-proxy: Essential for facilitating communication in stdio mode, enabling seamless interaction between the server and client.

# Streamlined Installation
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install mcp-proxy
uv tool update-shell

Configuration Essentials

A .env file is required to manage sensitive information and configure server behavior:

OPENAI_API_KEY=your-openai-api-key  # Your OpenAI API key for LLM integration
CHROME_PATH=optional/path/to/chrome # Optional: Specify a custom Chrome executable path
PATIENT=false  # Set to 'true' to ensure API calls wait for task completion, enhancing reliability

Installation Procedure

Follow these steps to install browser-use-mcp-server and its dependencies:

# Install project dependencies with uv
uv sync

# Install Playwright and its browser dependencies
uv pip install playwright
uv run playwright install --with-deps --no-shell chromium

Operational Modes

browser-use-mcp-server supports two distinct operational modes, each catering to different deployment scenarios:

1. Server-Sent Events (SSE) Mode

This mode offers a straightforward setup for direct communication:

# Launch the server directly from the source code
uv run server --port 8000

2. Standard Input/Output (stdio) Mode

This mode is ideal for environments requiring more controlled communication channels, often used in conjunction with mcp-proxy:

# 1. Build and install the package globally
uv build
uv tool uninstall browser-use-mcp-server 2>/dev/null || true # Ensure clean uninstall
uv tool install dist/browser_use_mcp_server-*.whl

# 2. Execute the server with stdio transport, leveraging mcp-proxy
browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000

Client Integration

To connect your AI client to browser-use-mcp-server, configure the mcpServers section in your client's configuration file. The specific location of this file varies depending on the client application.

SSE Mode Client Configuration

{
  "mcpServers": {
    "browser-use-mcp-server": {
      "url": "http://localhost:8000/sse"
    }
  }
}

stdio Mode Client Configuration

{
  "mcpServers": {
    "browser-server": {
      "command": "browser-use-mcp-server",
      "args": [
        "run",
        "server",
        "--port",
        "8000",
        "--stdio",
        "--proxy-port",
        "9000"
      ],
      "env": {
        "OPENAI_API_KEY": "your-api-key"
      }
    }
  }
}

Configuration File Locations (Examples)

Key Features

• Robust Browser Automation: Leverage the power of AI agents to control and interact with web browsers programmatically.
• Dual Transport Support: Choose between SSE and stdio modes to suit your specific deployment architecture and communication requirements.
• Real-time VNC Streaming: Monitor browser automation tasks visually with integrated VNC streaming capabilities.
• Asynchronous Task Execution: Execute browser operations asynchronously, maximizing efficiency and responsiveness.

Local Development Workflow

For contributing to or customizing browser-use-mcp-server, follow these steps:

1. Build a Distributable Wheel:

   # From the project root
   uv build

2. Install as a Global Tool:

   uv tool uninstall browser-use-mcp-server 2>/dev/null || true
   uv tool install dist/browser_use_mcp_server-*.whl

3. Run from Any Directory:

   # Set your OpenAI API key (either as an environment variable or inline)
   export OPENAI_API_KEY=your-api-key-here
   
   # Or:
   OPENAI_API_KEY=your-api-key-here browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000

4. Rebuild and Reinstall After Changes:

   uv build
   uv tool uninstall browser-use-mcp-server
   uv tool install dist/browser_use_mcp_server-*.whl

Docker Deployment

Docker provides a consistent and isolated environment for running browser-use-mcp-server.

# Build the Docker image
docker build -t browser-use-mcp-server .

# Run the container (default VNC password: "browser-use")
# -p 8000:8000 maps the server port
# -p 5900:5900 maps the VNC port
# --rm removes the container on exit
docker run --rm -p8000:8000 -p5900:5900 browser-use-mcp-server

# Run with a custom VNC password (more secure)
echo "your-secure-password" > vnc_password.txt
docker run --rm -p8000:8000 -p5900:5900 \
  -v $(pwd)/vnc_password.txt:/run/secrets/vnc_password:ro \
  browser-use-mcp-server

Security Note: The :ro flag in the volume mount ensures the password file is read-only within the container.

Accessing the VNC Viewer

# Browser-based viewer setup
git clone https://github.com/novnc/noVNC
cd noVNC
./utils/novnc_proxy --vnc localhost:5900

Default VNC password: browser-use (unless overridden).

Illustrative Example

Engage your AI with a task like:

open https://news.ycombinator.com and return the top ranked article

Support Resources

For assistance and inquiries, visit: cobrowser.xyz

Project Trajectory