JinsongRoh/pydoll-mcp

🤖 PyDoll MCP Server(pydoll-mcp) v1.1.3

The Ultimate Browser Automation MCP Server
Revolutionary zero-webdriver automation with intelligent captcha bypass

📢 Latest Updates (v1.1.3 - 2025-06-18)

🐛 Critical Bug Fixes

• ✅ Fixed JSON Parsing Errors: 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
• ✅ Enhanced Stability: Improved server startup and error handling

🌟 What Makes PyDoll MCP Server Revolutionary?

PyDoll MCP Server brings the groundbreaking capabilities of PyDoll to Claude, OpenAI, Gemini and other MCP clients. Unlike traditional browser automation tools that struggle with modern web protection, PyDoll operates at a fundamentally different level.

PyDoll GitHub and Installation Information

• GitHub: https://github.com/autoscrape-labs/pydoll
• How to install: pip install pydoll-python
• PyDoll version: PyDoll 2.2.1 (2025.06.17)

🚀 Key Breakthrough Features

• 🚫 Zero WebDrivers: Direct browser communication via Chrome DevTools Protocol
• 🧠 AI-Powered Captcha Bypass: Automatic Cloudflare Turnstile & reCAPTCHA v3 solving
• 👤 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
• 🌐 Real-time Network Control: Intercept, modify, and analyze all web traffic
• 🔧 One-Click Setup: Automatic Claude Desktop configuration
• 🌍 Universal Compatibility: Works on all systems including Korean Windows
• 🐛 MCP Protocol Compliant: Fixed JSON parsing issues for reliable communication

📋 What Can You Do?

🎯 Smart Web Automation

• Navigate websites with human-like behavior patterns
• Extract data from protected and dynamic websites
• Automate complex workflows across multiple pages
• Handle modern SPAs and dynamic content seamlessly

🛡️ Protection System Bypass

• Automatically solve Cloudflare Turnstile captchas
• Bypass reCAPTCHA v3 without external services
• Evade sophisticated bot detection systems
• Navigate through protected content areas

📊 Advanced Data Extraction

• Scrape data from modern protected websites
• Monitor and capture all network API calls
• Extract information from dynamic, JavaScript-heavy sites
• Handle complex authentication flows

🔍 Comprehensive Testing & Monitoring

• Test websites under realistic user conditions
• Monitor performance and network behavior
• Validate forms and user interactions
• Capture screenshots and generate reports

💻 Quick Installation & Setup

⚡ One-Command Installation (Recommended)

pip install pydoll-mcp

NEW in v1.1.0: The installation now automatically offers to configure Claude Desktop! 🎉

After installation, you'll see:

🤖 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

🚀 Alternative Setup Methods

Option 1: One-Click Auto Setup

# Install and configure everything automatically
pip install pydoll-mcp
python -m pydoll_mcp.cli auto-setup

Option 2: Manual Setup from Source

# Clone the repository
git clone https://github.com/JinsongRoh/pydoll-mcp.git
cd pydoll-mcp

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

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

Option 3: Docker Installation

# Pull and run the Docker container
docker run -d --name pydoll-mcp -p 8080:8080 jinsongroh/pydoll-mcp:latest

⚙️ Claude Desktop Integration

🔧 Automatic Setup (NEW! v1.1.0)

The easiest way to get started:

# After installing with pip, just run:
python -m pydoll_mcp.cli auto-setup

This will:

• ✅ Test your installation
• ✅ Locate your Claude Desktop config
• ✅ Backup existing configuration
• ✅ Add PyDoll MCP Server configuration
• ✅ Verify everything works

🛠️ Manual Setup Options

Automatic Setup Scripts

Windows:

# Download and run setup script
curl -o setup_claude.bat https://raw.githubusercontent.com/JinsongRoh/pydoll-mcp/main/setup/setup_claude_windows.bat
setup_claude.bat

Linux/macOS:

# Download and run setup script
curl -o setup_claude.sh https://raw.githubusercontent.com/JinsongRoh/pydoll-mcp/main/setup/setup_claude_unix.sh
chmod +x setup_claude.sh
./setup_claude.sh

Manual Configuration

If you prefer to configure manually, add this to your Claude Desktop config:

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:

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

Generate Config File

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

# Generate and auto-setup
python -m pydoll_mcp.cli generate-config --auto-setup

# Generate in different formats
python -m pydoll_mcp.cli generate-config --format yaml
python -m pydoll_mcp.cli generate-config --format env

🚀 Getting Started

1. Quick Start Guide

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

2. Test Your Installation

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

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

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

3. Basic Usage Examples

Basic Website Navigation:

"Start a browser and go to https://example.com"
"Take a screenshot of the current page"
"Find the search box and search for 'browser automation'"

Advanced Form Automation:

"Fill the login form with username 'test@example.com' and password 'secure123'"
"Upload the file 'document.pdf' to the file input"
"Submit the form and wait for the success message"

Protection Bypass:

"Enable Cloudflare bypass and navigate to the protected site"
"Automatically solve any captcha challenges that appear"
"Extract the protected content after bypassing security"

Data Extraction & Monitoring:

"Monitor all network requests while browsing this e-commerce site"
"Extract product information from all visible items"
"Capture API responses containing pricing data"

🛠️ Complete Tool Arsenal

🔧 Advanced Configuration

Performance Optimization

{
  "browser_config": {
    "headless": true,
    "disable_images": true,
    "disable_css": false,
    "block_ads": true,
    "enable_compression": true,
    "max_concurrent_tabs": 5
  },
  "network_config": {
    "timeout": 30,
    "retry_attempts": 3,
    "enable_caching": true,
    "throttle_requests": false
  }
}

Stealth Configuration

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

Captcha Bypass Settings

{
  "captcha_config": {
    "auto_solve_cloudflare": true,
    "auto_solve_recaptcha": true,
    "solve_timeout": 30,
    "retry_failed_attempts": 3,
    "human_behavior_simulation": true
  }
}

🛠️ Command Line Interface

PyDoll MCP Server comes with a powerful CLI for management and testing:

# Main commands
pydoll-mcp                          # Start MCP server
pydoll-mcp-test                     # Test installation
pydoll-mcp-setup                    # Setup Claude Desktop

# Module commands
python -m pydoll_mcp.server         # Start server
python -m pydoll_mcp.cli --help     # Show all CLI options

# Setup and configuration
python -m pydoll_mcp.cli auto-setup        # One-click setup
python -m pydoll_mcp.cli setup-claude      # Setup Claude Desktop only
python -m pydoll_mcp.cli quick-start       # Interactive guide
python -m pydoll_mcp.cli generate-config   # Generate config files

# Testing and diagnostics
python -m pydoll_mcp.cli test-installation --verbose
python -m pydoll_mcp.cli test-browser --browser chrome
python -m pydoll_mcp.cli status --logs --stats

# Maintenance
python -m pydoll_mcp.cli cleanup           # Clean temp files

🐛 Troubleshooting

Common Issues

Installation Problems

# Check Python version (requires 3.8+)
python --version

# Upgrade pip
python -m pip install --upgrade pip

# Install with verbose output
pip install pydoll-mcp -v

Browser Issues

# Verify browser installation
python -c "from pydoll.browser import Chrome; print('Browser check passed')"

# Test basic functionality
python -m pydoll_mcp.cli test-browser

# Check browser permissions
ls -la /usr/bin/google-chrome  # Linux

Connection Issues

# Test MCP server connection
python -m pydoll_mcp.server --test

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

# Verify Claude Desktop config
python -m pydoll_mcp.cli generate-config

MCP Communication Issues (NEW in v1.1.3!) - FIXED!

# For JSON parsing errors, upgrade to v1.1.3
pip install --upgrade pydoll-mcp

# Verify the fix
python -m pydoll_mcp.server --test

# Check server output (should be clean JSON)
python -m pydoll_mcp.cli status

Encoding Issues (Korean Windows / International Systems)

# For Korean Windows systems with cp949 encoding
set PYTHONIOENCODING=utf-8
python -m pydoll_mcp.server

# Alternative: Use command prompt with UTF-8
chcp 65001
python -m pydoll_mcp.server

# Permanent solution: Add to Claude Desktop config
{
  "mcpServers": {
    "pydoll": {
      "command": "python",
      "args": ["-m", "pydoll_mcp.server"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYDOLL_LOG_LEVEL": "INFO"
      }
    }
  }
}

Configuration Issues

# Re-run setup
python -m pydoll_mcp.cli auto-setup --force

# Check configuration
python -m pydoll_mcp.cli status

# Manual config generation
python -m pydoll_mcp.cli generate-config --auto-setup

Debug Mode

# Enable debug logging
export PYDOLL_DEBUG=1
export PYDOLL_LOG_LEVEL=DEBUG

# Run with detailed output
python -m pydoll_mcp.server --debug

📊 Performance Metrics

PyDoll MCP Server provides significant advantages over traditional automation:

🆕 What's New

v1.1.3 (Latest - 2025-06-18)

🐛 Critical Bug Fixes

• Fixed JSON Parsing Errors: Resolved critical JSON parsing errors that prevented MCP client communication
• Stdout/Stderr Separation: Modified banner output to use stderr instead of stdout for MCP protocol compliance
• Encoding Compatibility: Fixed character encoding issues on Korean Windows systems (CP949/EUC-KR)
• Protocol Compliance: Ensured all stdout output is valid JSON for proper MCP client integration
• Enhanced Error Handling: Improved error messages with proper JSON formatting for better client parsing
• Cross-Platform Stability: Better handling of international character encodings

v1.1.2

🛠️ Enhanced Stability

• Server Reliability: Improved server startup and shutdown processes
• Error Recovery: Better error handling and recovery mechanisms
• Performance Optimization: Reduced memory usage and improved response times

v1.1.1

🐛 Critical Bug Fixes

• Fixed Korean Windows Issue: Resolved UnicodeEncodeError that prevented server startup on Korean Windows systems
• Enhanced Encoding Support: Added comprehensive encoding detection and fallback mechanisms
• International Compatibility: Improved support for all non-English Windows environments
• Automatic Recovery: Added robust error recovery for encoding-related failures

v1.1.0

🔧 One-Click Setup

• Auto-configuration: Automatic Claude Desktop setup during pip installation
• Smart detection: Automatic detection of Claude Desktop config paths
• Safe merging: Intelligent merging with existing configurations
• Backup protection: Automatic backup of existing configurations

🚀 Enhanced CLI

• New Commands: auto-setup, setup-claude, quick-start
• Interactive guides: Step-by-step setup assistance
• Better diagnostics: Enhanced testing and status reporting
• Cross-platform: Improved Windows, macOS, and Linux support

🛠️ Developer Experience

• Post-install hooks: Automatic setup prompts after installation
• Multiple entry points: Various ways to access setup functionality
• Better error handling: More helpful error messages and recovery suggestions
• Documentation: Updated docs with new setup methods

🤝 Contributing

We welcome contributions! See our for details.

Development Setup

# Clone repository
git clone https://github.com/JinsongRoh/pydoll-mcp.git
cd pydoll-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\\Scripts\\activate   # Windows

# Install development dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# Setup pre-commit hooks
pre-commit install

Adding Features

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Add tests for new functionality
4. Ensure all tests pass: pytest
5. Submit a pull request

📚 Documentation & Resources

• Complete Documentation: Full user guide and API reference
• PyDoll Library: Core automation library documentation
• MCP Protocol: Model Context Protocol specification
• Examples Repository: Comprehensive automation examples

🔒 Security & Ethics

Responsible Use Guidelines

• Respect robots.txt: Honor website crawling policies
• Rate Limiting: Avoid overwhelming servers
• Legal Compliance: Ensure automation follows applicable laws
• Privacy: Handle data responsibly
• Terms of Service: Respect website terms

Security Features

• Sandboxed Execution: Isolated browser processes
• Secure Defaults: Conservative security settings
• Audit Logging: Comprehensive action logging
• Permission Model: Granular capability control

📈 Roadmap

v1.2.0 (Coming Soon)

• Firefox browser support
• Enhanced mobile device emulation
• Advanced form recognition
• Improved error handling
• GUI setup tool

v1.3.0 (Q3 2025)

• Visual element recognition
• Natural language to automation
• Cloud browser support
• Enterprise features

v2.0.0 (Future)

• AI-powered automation
• Self-healing scripts
• Advanced analytics
• Multi-platform support

💝 Support & Sponsorship

If you find PyDoll MCP Server valuable:

• ⭐ Star the repository on GitHub
• 🐛 Report issues and suggest improvements
• 💰 Sponsor the project for priority support
• 📢 Share with your network
• 📝 Write tutorials and blog posts

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• PyDoll Team: For the revolutionary automation library
• Anthropic: For Claude and the MCP protocol
• Open Source Community: For continuous improvements and feedback

Ready to revolutionize your browser automation?
Download Latest Release | Documentation | Community

PyDoll MCP Server - Where AI meets revolutionary browser automation! 🤖🚀