browser_ctl

The Browser CTL MCP Server is designed to facilitate the interaction of AI agents with web browsers, specifically using the Chrome browser. Built on Python Playwright, this server provides a suite of tools that allow for real-time browser control, including executing JavaScript, navigating to URLs, and managing browser states such as opening, closing, and taking screenshots. The server operates with a default info log level and is accessible via a specified endpoint. It is designed to be easily set up and run on both Linux and Windows platforms, with detailed installation instructions provided.

Features

• Real-time JavaScript execution in the browser using Playwright's evaluate method.
• Ability to navigate to specified URLs in real-time.
• Control over browser state with open and close functionalities.
• Capability to capture and return screenshots of the current browser page.
• Randomized sleep function to pause browser activity for a specified duration.

MCP Tools

• execute_javascript: Execute JavaScript code in real-time browser using Playwright's evaluate method and return the script's result.
• go_to_url: Visit a target URL in real-time browser.
• sleep_for: Browser sleep for a random seconds between begin and end.
• close_browser: Close the opened browser.
• open_browser: Open browser in real-time.
• take_browser_screenshot: Capture a screenshot of the current browser page and return a base64-encoded image.

Usage with Different Platforms

Linux

bash
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Clone the repo

bash
git clone https://github.com/biteval/browser_ctl.git

Go to the project dir

bash
cd browser_ctl

Create virtual environment and activate it

bash
uv init
uv venv

Activate virtual environment on Linux

bash
source .venv/bin/activate

Activate virtual environment on Windows

bash
.venv\Scripts\activate

Install dependencies on Linux

bash
uv add "mcp[cli]" httpx playwright

Install dependencies on Windows

bash
uv add mcp[cli] httpx playwright

Download playwright browser binaries

bash
python -m playwright install

Start the Browser CTL MCP Server

bash
python browser_ctl.py