Installation Guide - JinsongRoh/pydoll-mcp GitHub Wiki

๐Ÿš€ PyDoll MCP Server Installation Guide

This comprehensive guide walks you through installing PyDoll MCP Server on Windows, macOS, and Linux systems.

๐Ÿ“‹ Prerequisites

System Requirements

  • Python: 3.8 or higher (Recommended: 3.9+)
  • OS: Windows 10+, macOS 10.14+, Linux (Ubuntu 18.04+, CentOS 7+)
  • Browser: Chrome or Edge (auto-detected)
  • Memory: Minimum 4GB RAM (Recommended: 8GB)
  • Storage: 500MB free space

Pre-installation Checklist

  • Python 3.8+ installed
  • pip package manager available
  • Chrome or Edge browser installed
  • Internet connection (for package downloads)
  • Administrator/sudo privileges (for system-wide installation)

๐Ÿ”ง Installation Methods

Method 1: Quick Installation via pip (Recommended)

Windows

# Run Command Prompt or PowerShell as Administrator
# Install PyDoll MCP Server
pip install pydoll-mcp

# Verify installation
pydoll-mcp --version
python -m pydoll_mcp.server --test

macOS

# Open Terminal
# Install PyDoll MCP Server
pip install pydoll-mcp

# If permission issues occur:
pip install --user pydoll-mcp

# Verify installation
pydoll-mcp --version
python -m pydoll_mcp.server --test

Linux (Ubuntu/Debian)

# Update system packages
sudo apt update

# Install Python pip (if needed)
sudo apt install python3-pip

# Install PyDoll MCP Server
pip3 install pydoll-mcp

# Verify installation
pydoll-mcp --version
python3 -m pydoll_mcp.server --test

Linux (CentOS/RHEL)

# Enable EPEL repository
sudo yum install epel-release

# Install Python pip
sudo yum install python3-pip

# Install PyDoll MCP Server
pip3 install pydoll-mcp

# Verify installation
pydoll-mcp --version
python3 -m pydoll_mcp.server --test

Method 2: Development Installation from Source

Clone Repository

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

# Create virtual environment (recommended)
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

Method 3: Docker Installation

Installation Using Docker

# Download and run Docker image
docker run -d --name pydoll-mcp -p 8080:8080 jinsongroh/pydoll-mcp:latest

# Check container status
docker ps

# View container logs
docker logs pydoll-mcp

Using Docker Compose

# docker-compose.yml
version: '3.8'
services:
  pydoll-mcp:
    image: jinsongroh/pydoll-mcp:latest
    ports:
      - "8080:8080"
    environment:
      - PYDOLL_LOG_LEVEL=INFO
    volumes:
      - ./config:/app/config
# Start service
docker-compose up -d

# Check status
docker-compose ps

โš™๏ธ Configuration

Automatic Configuration (Recommended)

One-Click Auto Setup

# Run auto setup after installation
python -m pydoll_mcp.cli auto-setup

This command performs the following:

  • โœ… Test installation status
  • โœ… Verify Claude Desktop configuration file location
  • โœ… Backup existing configuration
  • โœ… Add PyDoll MCP Server configuration
  • โœ… Verify configuration works

Interactive Setup

# Step-by-step setup guide
python -m pydoll_mcp.cli quick-start

Manual 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

Configuration File Content

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

Generate Configuration File

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

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

๐Ÿ› ๏ธ Post-Installation Setup

Auto Setup Scripts

Windows Auto Setup

# 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

# 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

Environment Variable Setup

Windows

# Set environment variables
set PYDOLL_LOG_LEVEL=INFO
set PYTHONIOENCODING=utf-8

# Permanent setting
setx PYDOLL_LOG_LEVEL "INFO"
setx PYTHONIOENCODING "utf-8"

Linux/macOS

# Set for current session
export PYDOLL_LOG_LEVEL=INFO
export PYTHONIOENCODING=utf-8

# Permanent setting (add to ~/.bashrc or ~/.zshrc)
echo 'export PYDOLL_LOG_LEVEL=INFO' >> ~/.bashrc
echo 'export PYTHONIOENCODING=utf-8' >> ~/.bashrc

๐Ÿงช Installation Verification

Basic Testing

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

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

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

Detailed Testing

# Check Python version
python --version

# Verify package installation
pip show pydoll-mcp

# Verify browser detection
python -c "from pydoll.browser import Chrome; print('Chrome detection successful')"

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

๐Ÿ” Troubleshooting

Common Installation Issues

1. Python Version Issues

# Check Python version
python --version

# Recommended: Use Python 3.9 or higher
# Upgrade method varies by OS

2. pip Upgrade Required

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

# Detailed installation log
pip install pydoll-mcp -v

3. Permission Issues

# User installation (Linux/macOS)
pip install --user pydoll-mcp

# Administrator privileges (Windows)
# Run PowerShell as Administrator

4. Network Issues

# Increase timeout
pip install --timeout 60 pydoll-mcp

# Use different index
pip install -i https://pypi.org/simple/ pydoll-mcp

Browser-related Issues

Chrome Installation Check

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --version

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version

# Linux
google-chrome --version

Edge Installation Check

# Windows
"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --version

# macOS
/Applications/Microsoft\ Edge.app/Contents/MacOS/Microsoft\ Edge --version

# Linux
microsoft-edge --version

Encoding Issues (Korean Windows)

Fixing CP949 Encoding Issues

# Set UTF-8 in Command Prompt
chcp 65001

# Set environment variable
set PYTHONIOENCODING=utf-8

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

MCP Communication Issues

JSON Parsing Errors (Fixed in v1.1.3)

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

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

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

๐ŸŽฏ Advanced Installation Options

Development Environment Setup

# Install with development dependencies
pip install "pydoll-mcp[dev]"

# Install test tools
pip install "pydoll-mcp[test]"

# Install all dependencies
pip install "pydoll-mcp[dev,test]"

Virtual Environment Setup

# Create venv
python -m venv pydoll-env

# Activate
# Windows:
pydoll-env\Scripts\activate
# Linux/macOS:
source pydoll-env/bin/activate

# Install
pip install pydoll-mcp

Conda Environment Setup

# Create Conda environment
conda create -n pydoll-env python=3.9

# Activate environment
conda activate pydoll-env

# Install
pip install pydoll-mcp

๐Ÿš€ Next Steps After Installation

1. Quick Start

Follow the [โšก Quick Start Guide](Quick-Start) to run your first automation.

2. Learn Basic Usage

Check [๐ŸŽฏ Basic Usage](Basic-Usage) for basic commands and examples.

3. Explore Tools

See [๐Ÿ› ๏ธ Tools Reference](Tools-Reference) for all available tools.

4. Advanced Features

Learn performance optimization methods in [โš™๏ธ Advanced Configuration](Advanced-Configuration).

๐Ÿ’ก Installation Tips

Optimization Recommendations

  1. Use Virtual Environments: Isolated environments per project
  2. Use Latest Python: 3.9 or higher recommended
  3. Regular Updates: pip install --upgrade pydoll-mcp
  4. Check System Resources: Ensure sufficient memory and storage

Security Considerations

  1. Trusted Sources: Use official PyPI repository
  2. Permission Management: Grant only minimum necessary permissions
  3. Firewall Settings: Open only required ports
  4. Log Monitoring: Regular log checking

Installation Complete! ๐ŸŽ‰
You're now ready to use PyDoll MCP Server.

Quick Start | Configuration | Troubleshooting

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