Configuration - JinsongRoh/pydoll-mcp GitHub Wiki

๐Ÿ”ง Configuration - Claude Desktop Integration Setup

This guide explains how to configure PyDoll MCP Server integration with Claude Desktop so that AI assistants can use browser automation features.

๐Ÿš€ Automatic Setup (Recommended)

v1.1.0+ - One-Click Auto Setup

Starting from PyDoll MCP Server v1.1.0, automatic Claude Desktop configuration is provided after installation.

# Run auto setup after pip installation
pip install pydoll-mcp
python -m pydoll_mcp.cli auto-setup

After installation, the following options are provided:

๐Ÿค– 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

What Auto Setup Does

  • โœ… Test installation
  • โœ… Auto-detect Claude Desktop configuration file location
  • โœ… Backup existing configuration file
  • โœ… Add PyDoll MCP Server configuration
  • โœ… Verify all operations

๐Ÿ› ๏ธ Manual Configuration Method

1. Verify Configuration File Location

Claude Desktop configuration file locations by operating system:

Windows

%APPDATA%\Claude\claude_desktop_config.json

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

2. Add Basic Configuration

Add the following content to your Claude Desktop configuration file (claude_desktop_config.json):

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

3. Advanced Configuration Options

Enable Debug Mode

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

Encoding Configuration for Korean Windows Systems

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

๐Ÿ”ง Configuration via Automation Scripts

Windows Auto Setup Script

# 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 Auto Setup Script

# 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

๐Ÿ“‹ Configuration File Generation Tools

Configuration File Generation via CLI

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

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

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

Interactive Quick Start Guide

# Run interactive setup guide
python -m pydoll_mcp.cli quick-start

๐Ÿงช Configuration Verification and Testing

Check Installation Status

# Installation test (with detailed information)
python -m pydoll_mcp.cli test-installation --verbose

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

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

MCP Server Connection Test

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

# Check server status
python -m pydoll_mcp.cli status

๐Ÿ› Troubleshooting

Common Issues and Solutions

1. Installation Issues

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

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

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

2. Browser Issues

# Check 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 on Linux
ls -la /usr/bin/google-chrome

3. Connection Issues

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

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

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

4. JSON Parsing Errors (Fixed in v1.1.3)

# Upgrade to v1.1.3
pip install --upgrade pydoll-mcp

# Verify fixes
python -m pydoll_mcp.server --test

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

5. Korean Windows Encoding Issues

# Temporary solution
set PYTHONIOENCODING=utf-8
python -m pydoll_mcp.server

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

Configuration Reset

# Force reset
python -m pydoll_mcp.cli auto-setup --force

# Check configuration status
python -m pydoll_mcp.cli status

# Generate manual configuration file
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 verbose output
python -m pydoll_mcp.server --debug

๐Ÿ”ง Advanced Configuration

Performance Optimization Settings

{
  "mcpServers": {
    "pydoll": {
      "command": "python",
      "args": ["-m", "pydoll_mcp.server"],
      "env": {
        "PYDOLL_LOG_LEVEL": "INFO",
        "PYDOLL_BROWSER_CONFIG": "{\"headless\": true, \"disable_images\": true, \"block_ads\": true}",
        "PYDOLL_NETWORK_TIMEOUT": "30",
        "PYDOLL_MAX_CONCURRENT_TABS": "5"
      }
    }
  }
}

Stealth Mode Configuration

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

CAPTCHA Bypass Configuration

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

๐Ÿš€ Restart Claude Desktop

After completing configuration, restart Claude Desktop to apply changes:

  1. Completely close Claude Desktop
  2. Verify configuration file is saved
  3. Restart Claude Desktop
  4. Test PyDoll MCP Server functionality in a new conversation

โœ… Verify Configuration Completion

You can verify that PyDoll MCP Server is properly integrated with Claude Desktop using commands like:

"Start a browser and navigate to example.com"
"Take a screenshot of the current page"
"Check PyDoll MCP Server status"

Once configuration is complete, you can use powerful browser automation features through Claude! ๐ŸŽ‰