undetected-chrome-mcp: Instructions file for Claude Code

CLAUDE.md - Undetected Chrome MCP Server

🚨 CRITICAL: Docker Environment - Virtual Environment REQUIRED

YOU ARE IN A DOCKER CONTAINER. SYSTEM-WIDE PACKAGES DISAPPEAR ON RESTART.

MANDATORY: Always Use Virtual Environment

This project MUST use the virtual environment at ./venv/ for ALL operations:

• ✅ CORRECT: ./venv/bin/python or ./venv/bin/pip
• ❌ WRONG: python3 or pip install (these will be lost on Docker restart!)

Project Overview

undetected-chrome-mcp-server is a Model Context Protocol (MCP) server that provides browser automation capabilities using undetected-chromedriver for enhanced anti-detection compared to standard Puppeteer. It serves as a drop-in replacement for server-puppeteer with improved capabilities for bypassing modern anti-bot protections.

Key Achievement: Successfully bypasses Reddit's bot detection where standard Puppeteer fails.

Development Commands

Setup and Installation

# ALWAYS check venv exists first
if [ ! -d "venv" ]; then
    python3 -m venv venv
fi

# Install dependencies - ALWAYS use venv pip
./venv/bin/pip install mcp selenium undetected-chromedriver Pillow

# Verify installation
./venv/bin/python -c "import mcp, selenium, undetected_chromedriver; print('✅ All dependencies installed')"

Running the Server

# CORRECT - Uses venv Python
./venv/bin/python run_mcp_server.py
# or
./venv/bin/python -m undetected_chrome_mcp.server

# WRONG - Will fail due to missing dependencies
python3 run_mcp_server.py  # ❌ DO NOT USE

MCP Configuration (.mcp.json)

The server MUST be configured to use the venv Python:

{
  "undetected-chrome": {
    "command": "/workspace/reddit/undetected-chrome-mcp/venv/bin/python",
    "args": ["/workspace/reddit/undetected-chrome-mcp/run_mcp_server.py"],
    "cwd": "/workspace/reddit"
  }
}

Code Quality and Testing

# Run tests - ALWAYS use venv Python
./venv/bin/python test_reddit_automation.py
./venv/bin/python test_functions.py

# Install dev dependencies if needed
./venv/bin/pip install pytest black isort mypy ruff

# Then run quality checks
./venv/bin/pytest tests/
./venv/bin/black src/ tests/
./venv/bin/isort src/ tests/