What is Demcp Browser Use Mcp

demcp-browser-use-mcp is an MCP server that enables AI agents to control web browsers through the browser-use framework.

Use cases

Use cases include automated web scraping, testing web applications, and enabling AI agents to perform tasks in a browser environment.

How to use

To use demcp-browser-use-mcp, install the necessary prerequisites including Python 3.11, uv, Playwright, and mcp-proxy. Set up the environment by creating a .env file with required API keys and optional configurations. Clone the repository, create a virtual environment, and install dependencies before running the server.

Key features

Key features include browser automation using Playwright, integration with AI agents, and the ability to control web browsers programmatically.

Where to use

demcp-browser-use-mcp can be used in fields such as web automation, AI-driven testing, and any application requiring browser interaction by AI agents.

demcp_browser_mcp

Prerequisites

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

# Install prerequisites manually (Example for macOS using Homebrew)
brew install [email protected] # Ensure Python 3.11+ is installed
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install mcp-proxy
# Ensure uv's bin directory is in your PATH (e.g., ~/.cargo/bin)

Environment

Create a .env file in the project root:

OPENAI_API_KEY=your-api-key # Required
CHROME_PATH=optional/path/to/chrome # Optional, if not in standard location
OPENAI_MODEL=gpt-4o # Optional, defaults to gpt-4o-mini in server code
# ... other optional env vars

Installation

# Clone the repository
git clone <your-repository-url>
cd demcp_browser_mcp

# Create virtual environment (recommended)
uv venv
source .venv/bin/activate # On Linux/macOS
# .\.venv\Scripts\Activate.ps1 # On Windows PowerShell

# Install dependencies
uv sync

# Install Playwright browsers
uv run playwright install --with-deps --no-shell chromium

Automated Setup from Scratch (Using Scripts)

For a fresh machine setup, you can use the provided scripts to automate the installation of prerequisites and project setup.

Note: These scripts require user interaction (e.g., entering API keys, confirming installations, entering sudo passwords) and might need terminal restarts afterwards for PATH changes to take effect.

1. Download the appropriate script for your operating system (start.sh for macOS, start_linux.sh for Linux, start_windows.ps1 for Windows) to a convenient location.

2. Make the script executable:

   • macOS/Linux: Open your terminal, navigate to the script’s location, and run: chmod +x start.sh (or start_linux.sh)
   • Windows: No chmod needed, but you might need to adjust PowerShell’s execution policy. Open PowerShell as Administrator and run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser (confirm with ‘Y’). You only need to do this once.

3. Run the script:

   • macOS: ./start.sh
   • Linux: ./start_linux.sh
   • Windows: Open a regular PowerShell window (not as admin), navigate to the script’s location, and run .\start_windows.ps1. (Alternatively, use powershell -ExecutionPolicy Bypass -File .\start_windows.ps1 to bypass policy for one run).

4. Follow the prompts: The script will guide you through:

   • Checking/installing prerequisites (Python, Git, uv, mcp-proxy).
   • Asking for the Git repository URL to clone.
   • Asking for your OpenAI API Key (input is hidden).
   • Setting up the virtual environment and installing dependencies.
   • Optionally building and installing the tool globally.
   • Optionally starting the server.

5. After the script finishes:

   • Restart your terminal/PowerShell window to ensure PATH changes are applied.
   • Review the generated .env file in the project directory.
   • Configure your MCP client (e.g., Cursor) according to the instructions printed by the script and the Client Configuration section below.

Usage (Manual)

If not using the setup scripts or after manual setup:

SSE Mode

# Make sure you are in the project directory with venv activated
uv run server --port 8000

stdio Mode

Option 1: Build and install globally

# 1. Build and install
uv build
uv tool uninstall demcp_browser_mcp 2>/dev/null || true
uv tool install dist/demcp_browser_mcp-*.whl --force

# 2. Run (ensure uv tool path is in PATH)
demcp_browser_mcp run server --port 8000 --stdio --proxy-port 9000

Client Configuration

SSE Mode Client Configuration

{
  "mcpServers": {
    "demcp_browser_mcp": {
      "url": "http://localhost:8000/sse"
    }
  }
}

stdio Mode Client Configuration

If running script directly (Option 1 above):

If running globally installed tool (Option 2 above):

Config Locations

Features

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

Local Development

To develop and test the package locally:

1. Ensure prerequisites and dependencies are installed (see Installation).
2. Activate your virtual environment (source .venv/bin/activate or similar).
3. Make code changes.
4. Run the server directly for testing:

   python server/server.py --stdio
   

5. If installing globally:

   uv build
   uv tool install dist/demcp_browser_mcp-*.whl --force
   demcp_browser_mcp run server --stdio
   

Docker

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

# Build the Docker image
docker build -t demcp_browser_mcp .

# 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
# Pass OpenAI API Key as environment variable
docker run --rm -p8000:8000 -p5900:5900 -e OPENAI_API_KEY="your-api-key" demcp_browser_mcp

# Run with a custom VNC password read from a file
echo "your-secure-password" > vnc_password.txt
docker run --rm -p8000:8000 -p5900:5900 \
  -e OPENAI_API_KEY="your-api-key" \
  -v $(pwd)/vnc_password.txt:/run/secrets/vnc_password:ro \
  demcp_browser_mcp

Note: The Docker image runs the server in SSE mode by default. Modify the Dockerfile’s CMD instruction for stdio mode.

VNC Viewer

# Browser-based viewer (run on your host machine)
git clone https://github.com/novnc/noVNC
cd noVNC
./utils/launch.sh --vnc localhost:5900

Access http://localhost:6080/vnc.html in your browser.
Default password: browser-use (unless overridden using the custom password method in Dockerfile)

Example

Try asking your AI (configured with the MCP server):

@demcp_browser_mcp run task: open https://news.ycombinator.com and return the top 5 articles as a list

Support

For issues or inquiries: cobrowser.xyz

Star History