browser-use

What is browser-use-mcp-server?

browser-use-mcp-server is an MCP (Multi-Agent Communication Protocol) server designed to enable AI agents to control web browsers. It leverages Playwright for browser automation and provides functionalities for real-time VNC streaming of browser activity. This project is part of the browser-use ecosystem, facilitating AI interaction with web interfaces.

How to use browser-use-mcp-server?

To use browser-use-mcp-server, you need to install prerequisites like uv (a fast Python package manager) and Playwright. The server can be run in two modes: SSE (Server-Sent Events) mode or stdio (standard input/output) mode.

Installation:

1. Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
2. Install mcp-proxy: uv tool install mcp-proxy
3. Install dependencies: uv sync, uv pip install playwright, uv run playwright install --with-deps --no-shell chromium

Running the Server:

• SSE Mode: uv run server --port 8000
• stdio Mode: Build and install globally (uv build, uv tool install dist/browser_use_mcp_server-*.whl), then run browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000

Client Configuration:

Clients (like Cursor, Windsurf, Claude) need to be configured to connect to the MCP server. This involves setting the mcpServers configuration with the appropriate URL for SSE mode or command/arguments for stdio mode. Configuration file locations vary by client.

Docker:

For a consistent environment, you can build and run the Docker image:

docker build -t browser-use-mcp-server .
docker run --rm -p8000:8000 -p5900:5900 browser-use-mcp-server

Key Features of browser-use-mcp-server

• Browser Automation: Enables AI agents to programmatically control web browsers.
• Dual Transport: Supports both SSE and stdio protocols for flexible communication with AI clients.
• VNC Streaming: Allows real-time viewing of browser automation processes via VNC.
• Async Tasks: Supports asynchronous execution of browser operations.

Use Cases of browser-use-mcp-server

• AI Agent Development: Provides a robust backend for developing AI agents that interact with web applications.
• Automated Web Tasks: Automating repetitive web-based tasks through AI control.
• Testing and QA: Facilitating automated testing of web interfaces by AI.
• Data Extraction: Enabling AI to browse and extract information from websites.
• Interactive AI: Allowing AI to perform actions on websites based on user prompts, such as "open https://news.ycombinator.com and return the top ranked article."

FAQ about browser-use-mcp-server

• What are the prerequisites? uv (Python package manager), Playwright, and mcp-proxy (for stdio mode).
• How do I configure my AI client? You need to update the mcpServers configuration in your client's settings, specifying the server URL for SSE mode or the command/arguments for stdio mode.
• Can I watch the browser automation? Yes, through VNC streaming, which is supported by the server.
• Is there Docker support? Yes, a Dockerfile is provided for building and running the server in a containerized environment.
• Where can I get support? You can find support at cobrowser.xyz.

browser-use-mcp-server

An MCP server that enables AI agents to control web browsers using browser-use.

🔗 Managing multiple MCP servers? Simplify your development workflow with agent-browser

Prerequisites

• uv - Fast Python package manager
• Playwright - Browser automation
• mcp-proxy - Required for stdio mode

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

Environment

Create a .env file:

OPENAI_API_KEY=your-api-key
CHROME_PATH=optional/path/to/chrome
PATIENT=false  # Set to true if API calls should wait for task completion

Installation

# Install dependencies
uv sync
uv pip install playwright
uv run playwright install --with-deps --no-shell chromium

Usage

SSE Mode

# Run directly from source
uv run server --port 8000

stdio Mode

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

# 2. Run with stdio transport
browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000

Client Configuration

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"
      }
    }
  }
}

Config Locations

Client	Configuration Path
Cursor	./.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
Claude (Mac)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude (Windows)	%APPDATA%\Claude\claude_desktop_config.json

Features

• Browser Automation: Control browsers through AI agents
• Dual Transport: Support for both SSE and stdio protocols
• VNC Streaming: Watch browser automation in real-time
• Async Tasks: Execute browser operations asynchronously

Local Development

To develop and test the package locally:

1. Build a distributable wheel:

   # From the project root directory
   uv build
   

2. Install it 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 for the current session
   export OPENAI_API_KEY=your-api-key-here
   
   # Or provide it inline for a one-time run
   OPENAI_API_KEY=your-api-key-here browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000
   

4. After making changes, rebuild and reinstall:

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

Docker

Using Docker provides a consistent and isolated environment for running the server.

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

# Run the container with the default VNC password ("browser-use")
# --rm ensures the container is automatically removed when it stops
# -p 8000:8000 maps the server port
# -p 5900:5900 maps the VNC port
docker run --rm -p8000:8000 -p5900:5900 browser-use-mcp-server

# Run with a custom VNC password read from a file
# Create a file (e.g., vnc_password.txt) containing only your desired password
echo "your-secure-password" > vnc_password.txt
# Mount the password file as a secret inside the container
docker run --rm -p8000:8000 -p5900:5900 \
  -v $(pwd)/vnc_password.txt:/run/secrets/vnc_password:ro \
  browser-use-mcp-server

Note: The :ro flag in the volume mount (-v) makes the password file read-only inside the container for added security.

VNC Viewer

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

Default password: browser-use (unless overridden using the custom password method)

Example

Try asking your AI:

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

Support

For issues or inquiries: cobrowser.xyz

Star History