Browser Use MCP Server

🚀 Environment Variable Configuration

This project focuses on the configuration of environment variables for integrating and using custom browser instances in the MCP server. It provides clear guidance on setting up environment variables, starting the browser, and running the server, along with troubleshooting tips.

🚀 Quick Start

Step 1: Start Chrome Browser

Launch Chrome with the --remote-debugging-port flag:

google-chrome --remote-debugging-port=9222

If port 9222 is already in use, you can choose another port (e.g., 9223) and update the CHROME_CDP environment variable accordingly.

Step 2: Configure Environment Variables

Before starting the MCP server, set the following environment variables:

MCP_USE_OWN_BROWSER=true
CHROME_CDP=http://localhost:9222 # Use the same port as Chrome was launched with

Step 3: Run the MCP Server

Start the MCP server as usual:

uv run mcp-server-browser-use

✨ Features

• Connect to Existing Browser: Use MCP_USE_OWN_BROWSER=true to connect the server to an existing browser instance.
• Customizable CDP URL: Specify the Chrome DevTools Protocol URL via the CHROME_CDP environment variable.

📦 Installation

Environment Variable Configuration

MCP_USE_OWN_BROWSER

Set to true to instruct the server to connect to an existing browser instance.

CHROME_CDP

Specify the URL of the Chrome browser's DevTools Protocol. The format is as follows:

http://host:port

Example Configuration

Set the following in the .env file or system environment variables:

MCP_USE_OWN_BROWSER=true
CHROME_CDP=http://localhost:9222 # Use the same port as Chrome was launched with

💻 Usage Examples

Basic Usage

The basic usage involves setting up the environment variables, starting the browser, and running the MCP server as described in the Quick Start section.

Advanced Usage

For development and debugging, you can follow these steps:

# Install development dependencies and synchronize project dependencies
uv sync --dev

# Install Playwright browsers
uv run playwright install

# Use the debugging tool (example: connect to local Chrome)
# 1. Start Chrome: google-chrome --remote-debugging-port=9222
# 2. Run the debugging command:
npx @modelcontextprotocol/inspector@latest \
  -e OPENROUTER_API_KEY=$OPENROUTER_API_KEY \
  -e MCP_MODEL_PROVIDER=openrouter \
  -e MCP_MODEL_NAME=anthropic/claude-3.7-sonnet \
  -e MCP_USE_OWN_BROWSER=true \
  -e CHROME_CDP=http://localhost:9222 \
  uv --directory . run mcp run src/mcp_server_browser_use/server.py
# Note: Adjust the timeout as needed (default is 10 seconds)

📚 Documentation

Notes

• Browser State: When using MCP_USE_OWN_BROWSER=true, ensure that the Chrome browser remains open.
• Port Accessibility: Confirm that the CHROME_CDP URL is accessible to the MCP server (usually http://localhost:PORT on the same machine).
• Browser Window Size: The MCP server will use the actual size of the current Chrome window, rather than the settings in the environment variables.

Troubleshooting

• Browser Conflicts: When MCP_USE_OWN_BROWSER=false, ensure that no other Chrome instances are using the same user data directory.
• CDP Connection Issues:
  • Confirm that Chrome was launched with the --remote-debugging-port flag.
  • Check if the CHROME_CDP port is correct and ensure that no firewall is blocking access to this port.
  • Ensure that the browser instance is still running.
• API Errors: Check if the relevant API keys and configurations are correct.
• DevTools Protocol Issues: Confirm that the Chrome browser version supports the required DevTools features.

Image Explanation

This image demonstrates how to integrate and use a custom browser instance in the MCP server.