Customization - JinsongRoh/pydoll-mcp GitHub Wiki

🎨 Customization

PyDoll MCP Server provides comprehensive customization options that can be finely tuned for various use cases and environments. This guide explains how to optimize and configure the server to meet your specific requirements.

📋 Table of Contents

🌐 Environment Variables

PyDoll MCP Server can control various behaviors through environment variables.

Basic Environment Variables

# Log level setting (DEBUG, INFO, WARNING, ERROR, CRITICAL)
export PYDOLL_LOG_LEVEL=INFO

# Enable debug mode (0 or 1)
export PYDOLL_DEBUG=0

# Specify log file path
export PYDOLL_LOG_FILE=/path/to/logfile.log

# Browser type setting (chrome, edge)
export PYDOLL_BROWSER_TYPE=chrome

# Headless mode setting (true or false)
export PYDOLL_HEADLESS=true

# Enable stealth mode (true or false)
export PYDOLL_STEALTH_MODE=true

# Enable automatic CAPTCHA bypass (true or false)
export PYDOLL_AUTO_CAPTCHA_BYPASS=true

# Maximum number of browser instances
export PYDOLL_MAX_BROWSERS=3

# Maximum tabs per browser
export PYDOLL_MAX_TABS_PER_BROWSER=10

# Cleanup interval (seconds)
export PYDOLL_CLEANUP_INTERVAL=300

# Idle timeout (seconds)
export PYDOLL_IDLE_TIMEOUT=1800

# Character encoding setting (for Korean systems)
export PYTHONIOENCODING=utf-8

Windows System Environment Variables

# Windows Command Prompt
set PYDOLL_LOG_LEVEL=INFO
set PYTHONIOENCODING=utf-8

# Windows PowerShell
$env:PYDOLL_LOG_LEVEL="INFO"
$env:PYTHONIOENCODING="utf-8"

⚙️ Claude Desktop Configuration

Basic Configuration

Claude Desktop configuration file locations:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "pydoll": {
      "command": "python",
      "args": ["-m", "pydoll_mcp.server"],
      "env": {
        "PYDOLL_LOG_LEVEL": "INFO",
        "PYDOLL_DEBUG": "0",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

Advanced Claude Desktop Configuration

{
  "mcpServers": {
    "pydoll": {
      "command": "python",
      "args": ["-m", "pydoll_mcp.server"],
      "env": {
        "PYDOLL_LOG_LEVEL": "DEBUG",
        "PYDOLL_DEBUG": "1",
        "PYDOLL_BROWSER_TYPE": "chrome",
        "PYDOLL_HEADLESS": "true",
        "PYDOLL_STEALTH_MODE": "true",
        "PYDOLL_AUTO_CAPTCHA_BYPASS": "true",
        "PYDOLL_MAX_BROWSERS": "5",
        "PYDOLL_MAX_TABS_PER_BROWSER": "15",
        "PYTHONIOENCODING": "utf-8",
        "PYDOLL_LOG_FILE": "/tmp/pydoll-mcp.log"
      }
    }
  }
}

🌐 Browser Configuration

Performance Optimization Settings

{
  "browser_config": {
    "headless": true,
    "disable_images": true,
    "disable_css": false,
    "block_ads": true,
    "enable_compression": true,
    "max_concurrent_tabs": 5,
    "memory_limit": "2GB",
    "timeout": 30,
    "viewport": {
      "width": 1920,
      "height": 1080,
      "device_scale_factor": 1
    },
    "user_agent": "custom-agent-string",
    "proxy": {
      "server": "proxy-server:port",
      "username": "proxy-user",
      "password": "proxy-pass"
    }
  }
}

Custom Browser Arguments

# Custom browser arguments in development environment
browser_args = [
    "--no-sandbox",
    "--disable-dev-shm-usage",
    "--disable-gpu",
    "--disable-extensions",
    "--disable-plugins",
    "--disable-images",
    "--disable-javascript",
    "--disk-cache-size=0",
    "--memory-pressure-off",
    "--max_old_space_size=4096"
]

⚡ Performance Optimization

Memory Optimization

{
  "performance_config": {
    "memory_optimization": {
      "enable_memory_monitor": true,
      "max_memory_usage_mb": 2048,
      "cleanup_threshold_mb": 1500,
      "garbage_collection_interval": 60
    },
    "browser_optimization": {
      "max_concurrent_browsers": 3,
      "max_tabs_per_browser": 10,
      "tab_idle_timeout": 1800,
      "browser_idle_timeout": 3600
    }
  }
}

Network Optimization

{
  "network_config": {
    "timeout": 30,
    "retry_attempts": 3,
    "enable_caching": true,
    "throttle_requests": false,
    "connection_pool_size": 10,
    "max_redirects": 5,
    "user_agent_rotation": true,
    "request_delay": {
      "min": 1000,
      "max": 3000
    }
  }
}

🕵️ Stealth Mode Configuration

Advanced Stealth Settings

{
  "stealth_config": {
    "randomize_fingerprint": true,
    "rotate_user_agents": true,
    "humanize_timing": true,
    "evade_webrtc": true,
    "spoof_timezone": true,
    "mask_canvas": true,
    "disable_webgl": true,
    "randomize_fonts": true,
    "mouse_movement": {
      "enable_random_movement": true,
      "movement_speed": "human",
      "click_delay": {
        "min": 100,
        "max": 500
      }
    },
    "typing_behavior": {
      "typing_speed": "human",
      "random_pauses": true,
      "typo_probability": 0.02
    }
  }
}

User Agent Rotation

{
  "user_agent_config": {
    "rotation_enabled": true,
    "user_agents": [
      "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
      "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36"
    ],
    "random_selection": true,
    "update_interval": 3600
  }
}

🛡️ CAPTCHA Bypass Configuration

Cloudflare and reCAPTCHA Settings

{
  "captcha_config": {
    "auto_solve_cloudflare": true,
    "auto_solve_recaptcha": true,
    "solve_timeout": 30,
    "retry_failed_attempts": 3,
    "human_behavior_simulation": true,
    "cloudflare": {
      "challenge_timeout": 60,
      "turnstile_solver": "auto",
      "retry_on_failure": true
    },
    "recaptcha": {
      "v2_solver": "auto",
      "v3_solver": "auto",
      "score_threshold": 0.3,
      "audio_fallback": true
    }
  }
}

CAPTCHA Solving Strategies

{
  "captcha_strategies": {
    "primary_strategy": "ai_vision",
    "fallback_strategies": [
      "audio_processing",
      "human_simulation",
      "delay_retry"
    ],
    "confidence_threshold": 0.8,
    "max_attempts": 5
  }
}

🌐 Network Configuration

Proxy and Network Control

{
  "network_advanced": {
    "proxy_rotation": {
      "enabled": true,
      "proxy_list": [
        "proxy1.example.com:8080",
        "proxy2.example.com:8080"
      ],
      "rotation_interval": 300,
      "authentication": {
        "username": "proxy_user",
        "password": "proxy_pass"
      }
    },
    "request_interception": {
      "enabled": true,
      "block_resources": [
        "image",
        "stylesheet",
        "font",
        "media"
      ],
      "modify_headers": {
        "Accept-Language": "ko-KR,ko;q=0.9,en;q=0.8",
        "Accept-Encoding": "gzip, deflate, br"
      }
    },
    "traffic_monitoring": {
      "log_requests": true,
      "capture_responses": true,
      "filter_patterns": [
        "*.js",
        "*.css",
        "*.png"
      ]
    }
  }
}

📊 Logging and Debugging

Logging Configuration

{
  "logging_config": {
    "level": "INFO",
    "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    "handlers": {
      "console": {
        "enabled": true,
        "level": "INFO"
      },
      "file": {
        "enabled": true,
        "level": "DEBUG",
        "filename": "/var/log/pydoll-mcp.log",
        "max_size": "10MB",
        "backup_count": 5
      },
      "rotating": {
        "enabled": true,
        "level": "WARNING",
        "filename": "/var/log/pydoll-mcp-error.log",
        "when": "midnight",
        "interval": 1,
        "backup_count": 30
      }
    },
    "loggers": {
      "pydoll_mcp": "DEBUG",
      "pydoll": "INFO",
      "mcp": "WARNING"
    }
  }
}

Enable Debug Mode

# Detailed debugging in development environment
export PYDOLL_DEBUG=1
export PYDOLL_LOG_LEVEL=DEBUG

# Run server
python -m pydoll_mcp.server --debug

🐳 Docker Environment Configuration

Custom Docker Compose

version: '3.8'

services:
  pydoll-mcp:
    image: pydoll-mcp:latest
    container_name: pydoll-mcp-custom
    restart: unless-stopped
    
    environment:
      # Custom environment variables
      - PYDOLL_LOG_LEVEL=DEBUG
      - PYDOLL_BROWSER_TYPE=chrome
      - PYDOLL_HEADLESS=true
      - PYDOLL_STEALTH_MODE=true
      - PYDOLL_AUTO_CAPTCHA_BYPASS=true
      - PYDOLL_MAX_BROWSERS=5
      - PYDOLL_MAX_TABS_PER_BROWSER=15
      - PYDOLL_CLEANUP_INTERVAL=600
      - PYDOLL_IDLE_TIMEOUT=3600
      
    volumes:
      # Custom volume mounts
      - ./custom/logs:/app/logs
      - ./custom/screenshots:/app/screenshots
      - ./custom/downloads:/app/downloads
      - ./custom/config:/app/config
      - ./custom/chrome-data:/home/pydoll/.config/google-chrome
      
    ports:
      - "8080:8080"
      
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: '2.0'
        reservations:
          memory: 1G
          cpus: '1.0'

🛠️ Development Environment Setup

Developer Configuration

# Development environment variables
export PYDOLL_DEBUG=1
export PYDOLL_LOG_LEVEL=DEBUG
export PYDOLL_BROWSER_TYPE=chrome
export PYDOLL_HEADLESS=false

# Additional development options
export PYDOLL_ENABLE_DEVTOOLS=true
export PYDOLL_SLOW_MO=100
export PYDOLL_TRACE_ENABLED=true

Test Environment Configuration

{
  "test_config": {
    "browser_pool_size": 2,
    "test_timeout": 30,
    "headless_mode": true,
    "screenshot_on_failure": true,
    "video_recording": false,
    "trace_collection": true,
    "cleanup_after_test": true
  }
}

🔧 CLI Configuration

Configuration Generation and Management

# Generate default configuration file
python -m pydoll_mcp.cli generate-config

# Generate configuration in YAML format
python -m pydoll_mcp.cli generate-config --format yaml

# Generate configuration in environment variable format
python -m pydoll_mcp.cli generate-config --format env

# Automatic setup and configuration
python -m pydoll_mcp.cli auto-setup --advanced

Configuration Validation

# Check configuration status
python -m pydoll_mcp.cli status --logs --stats

# Test browser
python -m pydoll_mcp.cli test-browser --browser chrome --headless

# Validate installation
python -m pydoll_mcp.cli test-installation --verbose

📋 Configuration Examples

Minimal Configuration (Lightweight Mode)

{
  "minimal_config": {
    "browser_config": {
      "headless": true,
      "disable_images": true,
      "disable_css": true,
      "block_ads": true,
      "max_concurrent_tabs": 2
    },
    "performance": {
      "memory_limit": "512MB",
      "timeout": 15
    },
    "logging": {
      "level": "WARNING"
    }
  }
}

Maximum Performance Configuration

{
  "high_performance_config": {
    "browser_config": {
      "headless": true,
      "max_concurrent_tabs": 20,
      "memory_limit": "4GB",
      "enable_compression": true
    },
    "network": {
      "connection_pool_size": 50,
      "parallel_requests": 10
    },
    "stealth": {
      "minimal_stealth": true,
      "fast_mode": true
    }
  }
}

Security-Focused Configuration

{
  "security_focused_config": {
    "stealth_config": {
      "randomize_fingerprint": true,
      "rotate_user_agents": true,
      "humanize_timing": true,
      "evade_webrtc": true,
      "spoof_timezone": true,
      "mask_canvas": true
    },
    "proxy": {
      "rotation_enabled": true,
      "secure_protocols_only": true
    },
    "captcha": {
      "auto_solve_enabled": true,
      "human_simulation": true
    }
  }
}

🔍 Troubleshooting

Common Configuration Issues

# Validate configuration file
python -m pydoll_mcp.cli validate-config

# Fix permission issues
sudo chown -R $USER:$USER ~/.config/Claude/

# Fix encoding issues (Korean Windows)
chcp 65001
set PYTHONIOENCODING=utf-8

Performance Optimization Verification

# Monitor memory usage
python -m pydoll_mcp.cli monitor --memory

# Test network performance
python -m pydoll_mcp.cli test-network --verbose

# Browser performance benchmark
python -m pydoll_mcp.cli benchmark --iterations 10

📚 Additional Resources

Through this configuration guide, you can optimize PyDoll MCP Server to meet your specific requirements. If you need additional help or have questions, communicate with the community at [GitHub Discussions](https://github.com/JinsongRoh/pydoll-mcp/discussions).