Browser Management - JinsongRoh/pydoll-mcp GitHub Wiki

🌐 Browser Management

PyDoll MCP Server provides powerful browser management features that allow complete control of Chrome and Edge browsers. This guide explains how to create, manage, and monitor browser instances.

📋 Overview

PyDoll MCP Server's browser management system provides the following core features:

  • Browser Lifecycle Management: Creation, starting, and stopping of browser instances
  • Tab Management: Creating new tabs, closing, and switching active tabs
  • Resource Monitoring: Performance statistics and status monitoring
  • Automatic Cleanup: Automatic cleanup of idle browsers and resource optimization

🚀 Starting Browser

Basic Browser Start

Start Chrome browser in the simplest way:

Please start the browser

Starting Browser with Advanced Settings

Start browser with various option settings:

Please start Chrome browser in headless mode
and set window size to 1280x720

Available Browser Options:

Option Type Default Description
browser_type string "chrome" Browser type ("chrome" or "edge")
headless boolean false Run in headless mode
window_width integer 1920 Browser window width (pixels)
window_height integer 1080 Browser window height (pixels)
stealth_mode boolean true Enable detection evasion mode
proxy_server string - Proxy server (host:port format)
user_agent string - Custom User Agent
disable_images boolean false Disable image loading
block_ads boolean true Block advertisements
custom_args array - Additional browser arguments

Example Scenarios

High-performance scraping browser:

Please start headless Chrome browser with image loading disabled and ad blocking enabled

Development/testing browser:

Please start Edge browser with stealth mode disabled and window size set to 800x600

🗂️ Tab Management

Creating New Tab

Create a new tab in the browser:

Please create a new tab

Create tab that immediately navigates to specific URL:

Please create a new tab that navigates to https://example.com

Check Tab List

Check all currently open tabs:

Please show list of currently open tabs

Switch Active Tab

Switch to a specific tab:

Please switch to tab_123

Close Tab

Close unnecessary tabs:

Please close tab_123

📊 Browser Status Monitoring

Check Browser List

Check all running browsers:

Please show list of currently running browsers

Information returned:

  • Browser ID
  • Browser type (Chrome/Edge)
  • Creation time and uptime
  • Idle time
  • Number of open tabs
  • Performance statistics

Check Specific Browser Status

Check detailed status of a specific browser:

Please check status of browser_abc123

🛑 Browser Termination

Normal Termination

Safely terminate browser:

Please terminate browser_abc123

Force Termination

Force termination even with open tabs:

Please force terminate browser_abc123

⚙️ Environment Variable Settings

PyDoll MCP Server can control browser behavior through the following environment variables:

Basic Settings

# Default browser type
PYDOLL_BROWSER_TYPE=chrome

# Maximum concurrent browsers
PYDOLL_MAX_BROWSERS=3

# Maximum tabs per browser
PYDOLL_MAX_TABS_PER_BROWSER=10

# Idle browser cleanup interval (seconds)
PYDOLL_CLEANUP_INTERVAL=300

# Idle timeout (seconds)
PYDOLL_IDLE_TIMEOUT=1800

Browser Options

# Headless mode
PYDOLL_HEADLESS=false

# Window size
PYDOLL_WINDOW_WIDTH=1920
PYDOLL_WINDOW_HEIGHT=1080

# Stealth mode
PYDOLL_STEALTH_MODE=true

# Disable images
PYDOLL_DISABLE_IMAGES=false

# Proxy server
PYDOLL_PROXY_SERVER=127.0.0.1:8080

# Custom User Agent
PYDOLL_USER_AGENT="Custom User Agent"

🔧 Advanced Features

Automatic Resource Cleanup

PyDoll MCP Server provides the following automatic cleanup features:

  • Idle Browser Cleanup: Automatically terminate browsers unused for more than 30 minutes
  • Periodic Cleanup: Check and clean idle resources every 5 minutes
  • Memory Optimization: Control memory usage through browser instance limits

Performance Monitoring

Each browser instance tracks the following statistics:

  • Total number of tabs created
  • Total number of navigations
  • Total number of screenshots
  • Total number of scripts executed
  • Uptime and idle time

Error Handling

Errors that may occur during browser management:

  • Maximum browsers exceeded: Maximum number of browsers (3) reached
  • Maximum tabs exceeded: Maximum tabs per browser (10) reached
  • Browser instance not found: Browser instance {id} not found
  • PyDoll library missing: PyDoll library not available

💡 Usage Tips

1. Efficient Resource Usage

# Optimized browser for scraping
Please start Chrome browser in headless mode with image loading disabled

# Cleanup after work completion
Please terminate browser when work is complete

2. Multi-browser Workflow

# Simultaneous work with multiple browsers
Please start one Chrome browser and one Edge browser

# Separate work by browser
Chrome will handle site A, Edge will handle site B

3. Debugging and Monitoring

# Regular status checks
Please check status of all currently running browsers

# Performance statistics check
Please show list including performance statistics for each browser

🚨 Precautions

  1. Resource Limits: Limited to maximum 3 browsers and 10 tabs per browser by default
  2. Automatic Cleanup: Browsers unused for more than 30 minutes are automatically terminated
  3. Memory Usage: System memory usage may increase when many tabs are open
  4. PyDoll Dependency: PyDoll library must be installed to use browser features

📚 Related Documentation