FAQ - JinsongRoh/pydoll-mcp GitHub Wiki
Find answers to frequently asked questions. For more questions, please ask in [Issues](https://github.com/JinsongRoh/pydoll-mcp/issues).
- [What is PyDoll MCP Server?](#what-is-pydoll-mcp)
- [How to install?](#how-to-install)
- [How to integrate with Claude Desktop?](#claude-integration)
- [Auto setup doesn't work after installation](#auto-setup-issues)
- [How to set up manually?](#manual-setup)
- [JSON parsing error occurs](#json-parsing-error)
- [Encoding error on Korean Windows](#korean-encoding-error)
- [Browser doesn't start](#browser-not-starting)
- [Captcha bypass doesn't work](#captcha-bypass-not-working)
- [Network connection error occurs](#network-connection-error)
- [Which browsers are supported?](#supported-browsers)
- [What's the difference between headless and normal mode?](#headless-vs-normal)
- [What types of captcha can be bypassed?](#captcha-types)
- [How does network monitoring work?](#network-monitoring)
- [How to upload/download files?](#file-operations)
- [How to reduce memory usage?](#reduce-memory-usage)
- [How to improve speed?](#improve-speed)
- [Can I run multiple browsers simultaneously?](#multiple-browsers)
- [How to improve stability?](#improve-stability)
- [What is stealth mode?](#stealth-mode)
- [How to bypass bot detection?](#bot-detection-bypass)
- [Can I use proxies?](#proxy-support)
- [Can I change user agents?](#user-agent-rotation)
- [What are the major changes in v1.1.3?](#v113-changes)
- [How to upgrade from previous versions?](#upgrade-guide)
- [Is it compatible with other MCP clients?](#mcp-compatibility)
- [What are the Python version requirements?](#python-requirements)
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.
Answer: Installation is very simple:
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
# 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
Answer: Multiple ways to integrate:
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
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"
}
}
}
}
Answer: Try the following steps:
- 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
- Force reset
python -m pydoll_mcp.cli auto-setup --force
- Check config file directly
# Windows
type "%APPDATA%\Claude\claude_desktop_config.json"
# macOS/Linux
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
-
Restart Claude Desktop
- Completely close Claude Desktop
- Restart
- Check if "PyDoll" tool appears
Answer: Manual setup guide:
- Create config file
python -m pydoll_mcp.cli generate-config
-
Edit config file
- Windows: Open
%APPDATA%\Claude\claude_desktop_config.json
with Notepad - macOS/Linux: Open config file with text editor
- Windows: Open
-
Add/modify content
{
"mcpServers": {
"pydoll": {
"command": "python",
"args": ["-m", "pydoll_mcp.server"],
"env": {
"PYDOLL_LOG_LEVEL": "INFO",
"PYTHONIOENCODING": "utf-8"
}
}
}
}
- Validate configuration
python -m pydoll_mcp.cli test-installation --verbose
Answer: This issue has been fixed in v1.1.3!
- Upgrade to latest version
pip install --upgrade pydoll-mcp
- Check version
python -c "import pydoll_mcp; print(pydoll_mcp.__version__)"
# Should be 1.1.3 or higher
- Verify fixes
python -m pydoll_mcp.server --test
# Should output clean JSON
- 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
Answer: Korean Windows support has been greatly improved in v1.1.3!
- Set environment variables
set PYTHONIOENCODING=utf-8
python -m pydoll_mcp.server
- Change code page
chcp 65001
python -m pydoll_mcp.server
- 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"
}
}
}
}
- System locale setting: Windows Settings โ Time & Language โ Language โ Administrative language settings โ Use Unicode UTF-8 support
Answer: Step-by-step troubleshooting:
- Check browser installation
# Check if Chrome is installed
python -c "from pydoll.browser import Chrome; print('Browser check passed')"
- Test basic functionality
python -m pydoll_mcp.cli test-browser --browser chrome
- Resolve permission issues
# Check Chrome permissions on Linux
ls -la /usr/bin/google-chrome
# Try running Chrome directly
google-chrome --version
- Try headless mode
python -m pydoll_mcp.cli test-browser --browser chrome --headless
- Run in debug mode
export PYDOLL_DEBUG=1
export PYDOLL_LOG_LEVEL=DEBUG
python -m pydoll_mcp.server --debug
- Chrome not installed โ Install Chrome
- Insufficient permissions โ Run with administrator privileges
- Port conflicts โ Use different port
- Insufficient memory โ Check system resources
Answer: Captcha bypass optimization methods:
- Cloudflare Turnstile (95%+ success rate)
- reCAPTCHA v3 (90%+ success rate)
- Basic image captcha
- Enable stealth mode
# Ask Claude like this:
"Enable stealth mode and navigate to the protected site"
"Automatically solve any captcha challenges that appear"
- Use human behavior simulation
"Enable human behavior simulation before attempting captcha bypass"
- Adjust retry settings
{
"captcha_config": {
"auto_solve_cloudflare": true,
"auto_solve_recaptcha": true,
"solve_timeout": 30,
"retry_failed_attempts": 3,
"human_behavior_simulation": true
}
}
- Provide sufficient wait time
- Use natural mouse movements
- Avoid consistent patterns
- Randomize browser fingerprints
Answer: Network troubleshooting:
- Test connection
python -m pydoll_mcp.cli status --logs --stats
-
Check firewall settings
- Allow PyDoll MCP Server ports
- Allow Chrome DevTools Protocol port (9222)
-
Proxy configuration
# Ask Claude to use proxy:
"Start browser with proxy server 127.0.0.1:8080"
- Network condition simulation
"Simulate slow 3G network conditions for testing"
Answer: Currently supported browsers:
- Google Chrome (recommended)
- Microsoft Edge (Chromium-based)
- Mozilla Firefox
- Safari (macOS)
# 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"
Answer: Mode comparison:
Advantages:
- Real-time progress monitoring
- Easy debugging
- User interaction possible
- Higher captcha bypass success rate
Disadvantages:
- Uses more system resources
- Requires display
- Relatively slower
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
# Normal mode
"Start browser and take a screenshot of the homepage"
# Headless mode
"Start browser in headless mode and extract page data"
Answer: Supported captcha types and success rates:
- Cloudflare Turnstile
- Cloudflare Challenge Pages
- Basic JavaScript Challenge
- reCAPTCHA v3
- hCaptcha
- Simple Image Captcha
- Complex image captcha
- Audio captcha
- Math problem captcha
- reCAPTCHA v2 (Click Challenge)
- Complex puzzle captcha
- Custom captcha
# 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"
Answer: Comprehensive network analysis features:
- Real-time request/response capture
- Automatic API call extraction
- Header and payload analysis
- WebSocket connection tracking
- Performance metrics collection
# 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"
- Request URL and method
- Response status code
- Response time
- Data size
- Header information
- JSON/XML payload
Answer: Various file operations supported:
# 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"
# 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"
- 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
Answer: Memory optimization methods:
# 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"
{
"browser_config": {
"headless": true,
"disable_images": true,
"disable_css": false,
"block_ads": true,
"enable_compression": true,
"max_concurrent_tabs": 3
}
}
- 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
Answer: Performance optimization strategies:
# 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_config": {
"timeout": 15,
"retry_attempts": 2,
"enable_caching": true,
"throttle_requests": false,
"concurrent_connections": 10
}
}
Setting | Default | Optimized | Improvement |
---|---|---|---|
Page load | 3.2s | 1.1s | 65% โ |
Memory usage | 450MB | 180MB | 60% โ |
CPU usage | 35% | 15% | 57% โ |
Answer: Multi-browser support:
- Multiple browser instances running simultaneously
- Independent session management
- Tab isolation environment
- Resource distribution processing
# 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"
System RAM | Recommended Browsers | Tab Limit |
---|---|---|
8GB | 2 | 3/browser |
16GB | 4 | 5/browser |
32GB | 8 | 8/browser |
Answer: Stability improvement methods:
{
"stability_config": {
"auto_retry_failed_operations": true,
"max_retry_attempts": 3,
"retry_delay": 2,
"graceful_error_handling": true,
"automatic_cleanup": true
}
}
# 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"
- โ Set sufficient wait times
- โ Validate element existence before manipulation
- โ Check network status
- โ Implement error handling
- โ Regular status checks
- โ Automated resource cleanup
Answer: Advanced detection evasion technology:
- Browser fingerprint randomization
- User agent rotation
- WebRTC leak prevention
- Canvas fingerprint masking
- Timing attack prevention
- Automation detection bypass
# 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"
{
"stealth_config": {
"randomize_fingerprint": true,
"rotate_user_agents": true,
"humanize_timing": true,
"evade_webrtc": true,
"spoof_timezone": true,
"mask_canvas": true,
"disable_webgl": false
}
}
Answer: Multi-layer detection bypass system:
-
Behavior pattern simulation
- Natural mouse movements
- Human-like typing speed
- Realistic page dwell time
-
Technical bypass
- Direct Chrome DevTools Protocol usage
- WebDriver trace removal
- JavaScript execution context masking
-
Network level bypass
- Header spoofing
- Request pattern randomization
- Proxy rotation
# 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"
Answer: Complete proxy support:
- HTTP proxy
- HTTPS proxy
- SOCKS4/SOCKS5 proxy
- Authenticated proxy
# 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_config": {
"enabled": true,
"rotation": true,
"proxies": [
"http://proxy1:8080",
"http://proxy2:8080",
"socks5://proxy3:1080"
],
"auth": {
"username": "user",
"password": "pass"
}
}
}
Answer: Dynamic user agent management:
# 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"
- Desktop: Windows, macOS, Linux Chrome/Edge
- Mobile: Android, iOS Safari/Chrome
- Tablet: iPad, Android Tablet
- Custom: User-defined strings
{
"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)..."
]
}
}
Answer: v1.1.3 major improvements:
- โ 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
-
Full MCP protocol compliance
- Moved banner output to stderr
- Ensured all stdout output is valid JSON
- Prevented client parsing errors
-
Enhanced internationalization support
- Auto-detection of CP949, EUC-KR encoding
- UTF-8 fallback mechanism
- Multi-language system compatibility
-
Improved error handling
- Clearer error messages
- JSON-formatted error responses
- Automatic recovery for recoverable errors
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% โ |
Answer: Step-by-step upgrade guide:
# 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
# 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
- 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
- โ Check version (1.1.3+)
- โ Restart Claude Desktop
- โ Verify PyDoll tool functionality
- โ Run test automation
Answer: Broad MCP client support:
- Claude Desktop (Anthropic)
- Claude API with MCP
- OpenAI GPT with MCP
- Google Gemini with MCP
- Microsoft Copilot with MCP
- JSON-RPC 2.0 standard implementation
- Tool calls fully supported
- Schema validation automatic processing
- Error handling standardized
{
"mcpServers": {
"pydoll": {
"command": "python",
"args": ["-m", "pydoll_mcp.server"],
"env": {
"PYDOLL_LOG_LEVEL": "INFO",
"PYTHONIOENCODING": "utf-8"
}
}
}
}
- VSCode extension
- JetBrains IDE plugin
- Web-based clients
- Custom MCP clients
Answer: Python compatibility information:
- Python 3.8+ (minimum requirement)
- Python 3.9 (recommended)
- Python 3.10 (recommended)
- Python 3.11 (recommended)
- Python 3.12 (latest, recommended)
pydoll-python>=2.2.1
aiofiles>=0.8.0
asyncio>=3.4.3
websockets>=10.0
playwright>=1.30.0
- Windows 10/11 (x64)
- macOS 10.15+ (Intel/Apple Silicon)
- Linux Ubuntu 18.04+
- Linux CentOS 7+
- Linux Debian 10+
# Check Python version
python --version
python3 --version
# Check pip version
pip --version
# Test PyDoll MCP installation
python -c "import pydoll_mcp; print('โ
Installation OK')"
# 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
- [Complete Documentation](https://github.com/JinsongRoh/pydoll-mcp/wiki): Full user guide and API reference
- [PyDoll Library](https://autoscrape-labs.github.io/pydoll/): Core automation library documentation
- [Example Repository](https://github.com/JinsongRoh/pydoll-mcp/tree/main/examples): Comprehensive automation examples
- [GitHub Issues](https://github.com/JinsongRoh/pydoll-mcp/issues): Bug reports and feature requests
- [GitHub Discussions](https://github.com/JinsongRoh/pydoll-mcp/discussions): Questions and discussions
- [Discord Community](https://discord.gg/pydoll): Real-time chat support
# 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.