FAQ - JinsongRoh/pydoll-mcp GitHub Wiki

๐Ÿค– PyDoll MCP Server FAQ

Find answers to frequently asked questions. For more questions, please ask in [Issues](https://github.com/JinsongRoh/pydoll-mcp/issues).

๐Ÿ“‹ Table of Contents

๐Ÿ—๏ธ Installation & Setup

๐Ÿšจ Troubleshooting

๐Ÿ”ง Features & Usage

โšก Performance & Optimization

๐Ÿ›ก๏ธ Security & Evasion

๐Ÿ”„ Updates & Compatibility


๐Ÿ—๏ธ Installation & Setup

What is PyDoll MCP Server? {#what-is-pydoll-mcp}

Answer: PyDoll MCP Server is a revolutionary browser automation tool:

  • ๐Ÿšซ Zero WebDriver: Direct browser communication via Chrome DevTools Protocol
  • ๐Ÿง  AI-powered captcha bypass: Automatic solving of Cloudflare Turnstile & reCAPTCHA v3
  • ๐Ÿ‘ค Human behavior simulation: Undetectable interactions that fool sophisticated anti-bot systems
  • โšก Native async architecture: Lightning-fast concurrent automation
  • ๐Ÿ•ต๏ธ Advanced stealth mode: Anti-detection techniques that make automation invisible

Compatible with AI clients that support MCP, including Claude, OpenAI GPT, and Gemini.

How to install? {#how-to-install}

Answer: Installation is very simple:

๐Ÿš€ Recommended method (with auto setup)

pip install pydoll-mcp

After installation, auto setup options will appear automatically:

๐Ÿค– Setting up PyDoll MCP Server...

๐ŸŽ‰ PyDoll MCP Server installed successfully!
============================================================

๐Ÿš€ Quick Start Options:
1. ๐Ÿ”ง Auto-configure Claude Desktop
2. ๐Ÿ“‹ Generate config manually  
3. ๐Ÿงช Test installation
4. โญ๏ธ  Skip setup (configure later)

๐ŸŽฏ Choose an option (1-4): 1

๐Ÿ”ง Additional setup commands

# One-click auto setup
python -m pydoll_mcp.cli auto-setup

# Setup Claude Desktop only
python -m pydoll_mcp.cli setup-claude

# Interactive guide
python -m pydoll_mcp.cli quick-start

How to integrate with Claude Desktop? {#claude-integration}

Answer: Multiple ways to integrate:

๐Ÿ”ง Auto setup (easiest method)

python -m pydoll_mcp.cli auto-setup

This command automatically:

  • โœ… Tests installation
  • โœ… Finds Claude Desktop config file location
  • โœ… Backs up existing configuration
  • โœ… Adds PyDoll MCP Server configuration
  • โœ… Verifies everything works properly

๐Ÿ› ๏ธ Manual setup

Config 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

Configuration content:

{
  "mcpServers": {
    "pydoll": {
      "command": "python",
      "args": ["-m", "pydoll_mcp.server"],
      "env": {
        "PYDOLL_LOG_LEVEL": "INFO"
      }
    }
  }
}

Auto setup doesn't work after installation {#auto-setup-issues}

Answer: Try the following steps:

  1. Check permissions
# Check if Claude Desktop is installed
python -m pydoll_mcp.cli status

# Manually generate config
python -m pydoll_mcp.cli generate-config --auto-setup
  1. Force reset
python -m pydoll_mcp.cli auto-setup --force
  1. Check config file directly
# Windows
type "%APPDATA%\Claude\claude_desktop_config.json"

# macOS/Linux
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
  1. Restart Claude Desktop
    • Completely close Claude Desktop
    • Restart
    • Check if "PyDoll" tool appears

How to set up manually? {#manual-setup}

Answer: Manual setup guide:

  1. Create config file
python -m pydoll_mcp.cli generate-config
  1. Edit config file

    • Windows: Open %APPDATA%\Claude\claude_desktop_config.json with Notepad
    • macOS/Linux: Open config file with text editor
  2. Add/modify content

{
  "mcpServers": {
    "pydoll": {
      "command": "python",
      "args": ["-m", "pydoll_mcp.server"],
      "env": {
        "PYDOLL_LOG_LEVEL": "INFO",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
  1. Validate configuration
python -m pydoll_mcp.cli test-installation --verbose

๐Ÿšจ Troubleshooting

JSON parsing error occurs {#json-parsing-error}

Answer: This issue has been fixed in v1.1.3!

๐Ÿ”ง Solution:

  1. Upgrade to latest version
pip install --upgrade pydoll-mcp
  1. Check version
python -c "import pydoll_mcp; print(pydoll_mcp.__version__)"
# Should be 1.1.3 or higher
  1. Verify fixes
python -m pydoll_mcp.server --test
# Should output clean JSON

๐Ÿ’ก v1.1.3 fixes:

  • stdout/stderr separation: Moved banner output to stderr for MCP protocol compliance
  • JSON validity: Ensured all stdout output is valid JSON
  • Improved error handling: Better error messages and JSON formatting

Encoding error on Korean Windows {#korean-encoding-error}

Answer: Korean Windows support has been greatly improved in v1.1.3!

๐Ÿ”ง Immediate solutions:

  1. Set environment variables
set PYTHONIOENCODING=utf-8
python -m pydoll_mcp.server
  1. Change code page
chcp 65001
python -m pydoll_mcp.server
  1. Add encoding environment variable to Claude Desktop config
{
  "mcpServers": {
    "pydoll": {
      "command": "python",
      "args": ["-m", "pydoll_mcp.server"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYDOLL_LOG_LEVEL": "INFO"
      }
    }
  }
}

๐Ÿ’ก Permanent solution:

  • System locale setting: Windows Settings โ†’ Time & Language โ†’ Language โ†’ Administrative language settings โ†’ Use Unicode UTF-8 support

Browser doesn't start {#browser-not-starting}

Answer: Step-by-step troubleshooting:

  1. Check browser installation
# Check if Chrome is installed
python -c "from pydoll.browser import Chrome; print('Browser check passed')"
  1. Test basic functionality
python -m pydoll_mcp.cli test-browser --browser chrome
  1. Resolve permission issues
# Check Chrome permissions on Linux
ls -la /usr/bin/google-chrome

# Try running Chrome directly
google-chrome --version
  1. Try headless mode
python -m pydoll_mcp.cli test-browser --browser chrome --headless
  1. Run in debug mode
export PYDOLL_DEBUG=1
export PYDOLL_LOG_LEVEL=DEBUG
python -m pydoll_mcp.server --debug

๐Ÿ” Common causes and solutions:

  • Chrome not installed โ†’ Install Chrome
  • Insufficient permissions โ†’ Run with administrator privileges
  • Port conflicts โ†’ Use different port
  • Insufficient memory โ†’ Check system resources

Captcha bypass doesn't work {#captcha-bypass-not-working}

Answer: Captcha bypass optimization methods:

๐Ÿง  Supported captcha types:

  • Cloudflare Turnstile (95%+ success rate)
  • reCAPTCHA v3 (90%+ success rate)
  • Basic image captcha

๐Ÿ”ง Improve bypass performance:

  1. Enable stealth mode
# Ask Claude like this:
"Enable stealth mode and navigate to the protected site"
"Automatically solve any captcha challenges that appear"
  1. Use human behavior simulation
"Enable human behavior simulation before attempting captcha bypass"
  1. Adjust retry settings
{
  "captcha_config": {
    "auto_solve_cloudflare": true,
    "auto_solve_recaptcha": true,
    "solve_timeout": 30,
    "retry_failed_attempts": 3,
    "human_behavior_simulation": true
  }
}

๐Ÿ’ก Tips to increase success rate:

  • Provide sufficient wait time
  • Use natural mouse movements
  • Avoid consistent patterns
  • Randomize browser fingerprints

Network connection error occurs {#network-connection-error}

Answer: Network troubleshooting:

  1. Test connection
python -m pydoll_mcp.cli status --logs --stats
  1. Check firewall settings

    • Allow PyDoll MCP Server ports
    • Allow Chrome DevTools Protocol port (9222)
  2. Proxy configuration

# Ask Claude to use proxy:
"Start browser with proxy server 127.0.0.1:8080"
  1. Network condition simulation
"Simulate slow 3G network conditions for testing"

๐Ÿ”ง Features & Usage

Which browsers are supported? {#supported-browsers}

Answer: Currently supported browsers:

โœ… Fully supported:

  • Google Chrome (recommended)
  • Microsoft Edge (Chromium-based)

๐Ÿ”„ Coming soon (v1.2.0):

  • Mozilla Firefox
  • Safari (macOS)

๐Ÿ› ๏ธ Browser-specific settings:

# Use Chrome (default)
"Start Chrome browser with stealth mode enabled"

# Use Edge
"Start Microsoft Edge browser with ad blocking enabled"

# Headless mode
"Start browser in headless mode for background automation"

What's the difference between headless and normal mode? {#headless-vs-normal}

Answer: Mode comparison:

๐Ÿ–ฅ๏ธ Normal mode (with GUI):

Advantages:

  • Real-time progress monitoring
  • Easy debugging
  • User interaction possible
  • Higher captcha bypass success rate

Disadvantages:

  • Uses more system resources
  • Requires display
  • Relatively slower

๐Ÿ‘ป Headless mode (no GUI):

Advantages:

  • Fast execution speed
  • Lower memory usage
  • Can run in server environment
  • Suitable for background tasks

Disadvantages:

  • Some captcha bypass limitations
  • Difficult debugging
  • No visual confirmation

๐Ÿ”ง Usage:

# Normal mode
"Start browser and take a screenshot of the homepage"

# Headless mode  
"Start browser in headless mode and extract page data"

What types of captcha can be bypassed? {#captcha-types}

Answer: Supported captcha types and success rates:

๐Ÿฅ‡ High success rate (95%+):

  • Cloudflare Turnstile
  • Cloudflare Challenge Pages
  • Basic JavaScript Challenge

๐Ÿฅˆ Medium success rate (90%+):

  • reCAPTCHA v3
  • hCaptcha
  • Simple Image Captcha

๐Ÿฅ‰ Limited support (70%+):

  • Complex image captcha
  • Audio captcha
  • Math problem captcha

๐Ÿšซ Not supported:

  • reCAPTCHA v2 (Click Challenge)
  • Complex puzzle captcha
  • Custom captcha

๐Ÿ’ก Optimization methods:

# Enable automatic captcha bypass
"Enable automatic captcha bypass and navigate to protected site"

# Use with stealth mode
"Enable stealth mode and automatically solve captcha challenges"

# Human behavior simulation
"Simulate human behavior and solve captcha with natural timing"

How does network monitoring work? {#network-monitoring}

Answer: Comprehensive network analysis features:

๐Ÿ“Š Monitoring capabilities:

  • Real-time request/response capture
  • Automatic API call extraction
  • Header and payload analysis
  • WebSocket connection tracking
  • Performance metrics collection

๐Ÿ”ง Usage methods:

# Basic network monitoring
"Enable network monitoring and browse this e-commerce website"

# Automatic API response extraction
"Monitor all API calls and extract product pricing data"

# Filter specific requests
"Monitor only POST requests to the login endpoint"

# Performance analysis
"Analyze page load performance and network timing"

๐Ÿ“ˆ Output information:

  • Request URL and method
  • Response status code
  • Response time
  • Data size
  • Header information
  • JSON/XML payload

How to upload/download files? {#file-operations}

Answer: Various file operations supported:

๐Ÿ“ค File upload:

# Single file upload
"Find the file input and upload document.pdf"

# Multiple file upload
"Upload multiple images to the gallery: image1.jpg, image2.png"

# Drag and drop upload
"Drag and drop the file onto the upload area"

๐Ÿ“ฅ File download:

# Click link download
"Click the download link and save the file"

# Right-click download
"Right-click the image and save it to downloads folder"

# Programmatic download
"Download all PDF files from this page programmatically"

๐Ÿ—‚๏ธ Supported file formats:

  • Images: JPG, PNG, GIF, WebP, SVG
  • Documents: PDF, DOC, DOCX, XLS, XLSX
  • Archives: ZIP, RAR, 7Z
  • Media: MP4, MP3, AVI
  • Code: TXT, CSV, JSON, XML

โšก Performance & Optimization

How to reduce memory usage? {#reduce-memory-usage}

Answer: Memory optimization methods:

๐Ÿ”ง Browser settings optimization:

# Disable images
"Start browser with images disabled for faster loading"

# Enable ad blocking
"Enable ad blocking to reduce memory usage"

# Use headless mode
"Use headless mode for background automation tasks"

โš™๏ธ Advanced settings:

{
  "browser_config": {
    "headless": true,
    "disable_images": true,
    "disable_css": false,
    "block_ads": true,
    "enable_compression": true,
    "max_concurrent_tabs": 3
  }
}

๐Ÿ’ก Memory management tips:

  • Limit tab count: Use only 3-5 tabs simultaneously
  • Regular cleanup: Close unused tabs
  • Cache management: Periodically clear browser cache
  • Disable extensions: Remove unnecessary extensions

How to improve speed? {#improve-speed}

Answer: Performance optimization strategies:

๐Ÿš€ Immediately applicable optimizations:

# Headless mode + disable images
"Start browser in headless mode with images disabled"

# Enable network caching
"Enable network caching for repeated requests"

# Block unnecessary resources
"Block ads, trackers, and analytics for faster loading"

โš™๏ธ Network optimization:

{
  "network_config": {
    "timeout": 15,
    "retry_attempts": 2,
    "enable_caching": true,
    "throttle_requests": false,
    "concurrent_connections": 10
  }
}

๐Ÿ“Š Performance comparison:

Setting Default Optimized Improvement
Page load 3.2s 1.1s 65% โ†‘
Memory usage 450MB 180MB 60% โ†“
CPU usage 35% 15% 57% โ†“

Can I run multiple browsers simultaneously? {#multiple-browsers}

Answer: Multi-browser support:

๐Ÿ”„ Concurrent execution features:

  • Multiple browser instances running simultaneously
  • Independent session management
  • Tab isolation environment
  • Resource distribution processing

๐Ÿ› ๏ธ Usage methods:

# First browser
"Start first browser for social media automation"

# Second browser (concurrent)
"Start second browser for e-commerce data extraction"

# List browsers
"List all active browser instances with their status"

# Select specific browser
"Switch to browser instance 1 for the next operations"

๐Ÿ“Š Recommended concurrent numbers:

System RAM Recommended Browsers Tab Limit
8GB 2 3/browser
16GB 4 5/browser
32GB 8 8/browser

How to improve stability? {#improve-stability}

Answer: Stability improvement methods:

๐Ÿ›ก๏ธ Error recovery settings:

{
  "stability_config": {
    "auto_retry_failed_operations": true,
    "max_retry_attempts": 3,
    "retry_delay": 2,
    "graceful_error_handling": true,
    "automatic_cleanup": true
  }
}

๐Ÿ”ง Stability optimization:

# Set sufficient wait times
"Wait for page to fully load before proceeding"

# Verify element existence before manipulation
"Wait for the button to be visible and clickable before clicking"

# Check network stability
"Wait for network to be idle before extracting data"

# Automatic recovery on errors
"If an error occurs, automatically retry the operation"

๐Ÿ’ก Stability checklist:

  • โœ… Set sufficient wait times
  • โœ… Validate element existence before manipulation
  • โœ… Check network status
  • โœ… Implement error handling
  • โœ… Regular status checks
  • โœ… Automated resource cleanup

๐Ÿ›ก๏ธ Security & Evasion

What is stealth mode? {#stealth-mode}

Answer: Advanced detection evasion technology:

๐Ÿ•ต๏ธ Stealth mode features:

  • Browser fingerprint randomization
  • User agent rotation
  • WebRTC leak prevention
  • Canvas fingerprint masking
  • Timing attack prevention
  • Automation detection bypass

๐Ÿ”ง Activation methods:

# Basic stealth mode
"Enable stealth mode and navigate to the protected website"

# Advanced stealth settings
"Enable advanced stealth mode with fingerprint randomization"

# Specific detection bypass
"Bypass WebRTC detection and mask canvas fingerprint"

โš™๏ธ Advanced settings:

{
  "stealth_config": {
    "randomize_fingerprint": true,
    "rotate_user_agents": true,
    "humanize_timing": true,
    "evade_webrtc": true,
    "spoof_timezone": true,
    "mask_canvas": true,
    "disable_webgl": false
  }
}

How to bypass bot detection? {#bot-detection-bypass}

Answer: Multi-layer detection bypass system:

๐Ÿง  Detection bypass techniques:

  1. Behavior pattern simulation

    • Natural mouse movements
    • Human-like typing speed
    • Realistic page dwell time
  2. Technical bypass

    • Direct Chrome DevTools Protocol usage
    • WebDriver trace removal
    • JavaScript execution context masking
  3. Network level bypass

    • Header spoofing
    • Request pattern randomization
    • Proxy rotation

๐ŸŽฏ Real usage examples:

# Comprehensive detection bypass
"Enable comprehensive bot detection bypass for this banking website"

# Human behavior simulation
"Simulate realistic human browsing patterns with random delays"

# Advanced evasion techniques
"Use advanced evasion techniques for sophisticated protection"

Can I use proxies? {#proxy-support}

Answer: Complete proxy support:

๐ŸŒ Supported proxy types:

  • HTTP proxy
  • HTTPS proxy
  • SOCKS4/SOCKS5 proxy
  • Authenticated proxy

๐Ÿ”ง Proxy configuration:

# HTTP proxy
"Start browser with HTTP proxy 127.0.0.1:8080"

# Authenticated proxy
"Use proxy 127.0.0.1:8080 with username 'user' and password 'pass'"

# Proxy rotation
"Rotate between multiple proxy servers for each request"

# Direct connection without proxy
"Bypass proxy and connect directly for this request"

๐Ÿ”„ Proxy rotation settings:

{
  "proxy_config": {
    "enabled": true,
    "rotation": true,
    "proxies": [
      "http://proxy1:8080",
      "http://proxy2:8080", 
      "socks5://proxy3:1080"
    ],
    "auth": {
      "username": "user",
      "password": "pass"
    }
  }
}

Can I change user agents? {#user-agent-rotation}

Answer: Dynamic user agent management:

๐Ÿ”„ Automatic rotation:

# Automatic user agent rotation
"Enable automatic user agent rotation for each request"

# Specific OS simulation
"Use Windows 10 Chrome user agents only"

# Mobile device simulation
"Rotate between different mobile device user agents"

๐Ÿ“ฑ Device-specific user agents:

  • Desktop: Windows, macOS, Linux Chrome/Edge
  • Mobile: Android, iOS Safari/Chrome
  • Tablet: iPad, Android Tablet
  • Custom: User-defined strings

โš™๏ธ Rotation settings:

{
  "user_agent_config": {
    "rotation_enabled": true,
    "rotation_interval": 50,
    "device_types": ["desktop", "mobile"],
    "custom_agents": [
      "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
      "Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1)..."
    ]
  }
}

๐Ÿ”„ Updates & Compatibility

What are the major changes in v1.1.3? {#v113-changes}

Answer: v1.1.3 major improvements:

๐Ÿ› Core bug fixes:

  • โœ… JSON parsing error fixed: Resolved MCP client communication issues
  • โœ… Encoding compatibility: Full support for Korean Windows systems (CP949/EUC-KR)
  • โœ… Protocol compliance: Proper stdout/stderr separation for MCP compatibility
  • โœ… Stability improvements: Enhanced server startup and error handling

๐Ÿ”ง Technical improvements:

  1. Full MCP protocol compliance

    • Moved banner output to stderr
    • Ensured all stdout output is valid JSON
    • Prevented client parsing errors
  2. Enhanced internationalization support

    • Auto-detection of CP949, EUC-KR encoding
    • UTF-8 fallback mechanism
    • Multi-language system compatibility
  3. Improved error handling

    • Clearer error messages
    • JSON-formatted error responses
    • Automatic recovery for recoverable errors

๐Ÿ“Š Performance comparison:

Metric v1.1.2 v1.1.3 Improvement
Startup success rate 85% 99% 16% โ†‘
Encoding errors Frequent Rare 95% โ†“
JSON parsing success 70% 99% 41% โ†‘

How to upgrade from previous versions? {#upgrade-guide}

Answer: Step-by-step upgrade guide:

๐Ÿš€ Quick upgrade (recommended):

# Upgrade to latest version
pip install --upgrade pydoll-mcp

# Check version
python -c "import pydoll_mcp; print(pydoll_mcp.__version__)"

# Validate configuration
python -m pydoll_mcp.cli status

๐Ÿ”„ Complete reinstall (if issues occur):

# Remove existing version
pip uninstall pydoll-mcp

# Clear cache
pip cache purge

# Fresh install
pip install pydoll-mcp

# Auto setup
python -m pydoll_mcp.cli auto-setup

โš ๏ธ Important notes:

  • v1.0.x โ†’ v1.1.x: Config file compatible (no reconfiguration needed)
  • v1.1.0-1.1.2 โ†’ v1.1.3: Immediate upgrade recommended
  • Claude Desktop restart required

๐Ÿ“‹ Post-upgrade checklist:

  • โœ… Check version (1.1.3+)
  • โœ… Restart Claude Desktop
  • โœ… Verify PyDoll tool functionality
  • โœ… Run test automation

Is it compatible with other MCP clients? {#mcp-compatibility}

Answer: Broad MCP client support:

โœ… Fully supported:

  • Claude Desktop (Anthropic)
  • Claude API with MCP
  • OpenAI GPT with MCP
  • Google Gemini with MCP
  • Microsoft Copilot with MCP

๐Ÿ”ง Standard MCP protocol compliance:

  • JSON-RPC 2.0 standard implementation
  • Tool calls fully supported
  • Schema validation automatic processing
  • Error handling standardized

๐Ÿ’ก Client-specific configuration:

{
  "mcpServers": {
    "pydoll": {
      "command": "python",
      "args": ["-m", "pydoll_mcp.server"],
      "env": {
        "PYDOLL_LOG_LEVEL": "INFO",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

๐Ÿš€ Future support plans:

  • VSCode extension
  • JetBrains IDE plugin
  • Web-based clients
  • Custom MCP clients

What are the Python version requirements? {#python-requirements}

Answer: Python compatibility information:

โœ… Supported Python versions:

  • Python 3.8+ (minimum requirement)
  • Python 3.9 (recommended)
  • Python 3.10 (recommended)
  • Python 3.11 (recommended)
  • Python 3.12 (latest, recommended)

๐Ÿ”ง Required dependencies:

pydoll-python>=2.2.1
aiofiles>=0.8.0
asyncio>=3.4.3
websockets>=10.0
playwright>=1.30.0

๐Ÿ’ป Operating system support:

  • Windows 10/11 (x64)
  • macOS 10.15+ (Intel/Apple Silicon)
  • Linux Ubuntu 18.04+
  • Linux CentOS 7+
  • Linux Debian 10+

๐Ÿ Python installation check:

# Check Python version
python --version
python3 --version

# Check pip version
pip --version

# Test PyDoll MCP installation
python -c "import pydoll_mcp; print('โœ… Installation OK')"

๐Ÿ“ฆ Virtual environment recommended:

# Create virtual environment
python -m venv pydoll-env

# Activate (Windows)
pydoll-env\Scripts\activate

# Activate (Linux/macOS)  
source pydoll-env/bin/activate

# Install
pip install pydoll-mcp

๐Ÿ†˜ Need Additional Help?

๐Ÿ“š Resources

๐Ÿ’ฌ Community Support

๐ŸŽฏ Quick Help

# Comprehensive status check
python -m pydoll_mcp.cli status --verbose

# Full system test
python -m pydoll_mcp.cli test-installation --all

# Interactive help
python -m pydoll_mcp.cli help --interactive

๐Ÿค– Experience revolutionary browser automation with PyDoll MCP Server!
For more information and updates, check the GitHub repository.

โš ๏ธ **GitHub.com Fallback** โš ๏ธ