PyPen MCP

Model Context Protocol server for browser-based penetration testing using PyDoll.

Overview

PyPen MCP provides a comprehensive set of tools for LLM-powered browser automation and security testing. It leverages PyDoll's Chrome DevTools Protocol integration for reliable, webdriver-free browser control.

Features

Browser Management

• Launch/close browser instances with configurable options

• Navigation control (navigate, back, forward, refresh)

• Headless mode, proxy support, custom user agents

• Incognito mode and resource blocking

Network Operations

• Monitoring: Capture all HTTP traffic, analyze requests/responses

• Interception: Block, modify, or mock requests in real-time

• Authenticated Requests: Make API calls that inherit browser session/cookies

DOM Manipulation

• Find elements by CSS selector, XPath, or attributes

• Click, type, scroll, and interact with elements

• Extract page source, element text, and HTML

• Human-like scrolling with physics simulation

JavaScript Execution

• Execute arbitrary JavaScript in browser context

• Access localStorage and sessionStorage

• Extract global variables, forms, and links

Session Management

• Cookie manipulation (get, set, delete, clear)

• Import/export cookies in multiple formats

• Session-aware HTTP requests

Captcha Handling

• Turnstile Bypass: Automatic Cloudflare Turnstile interaction

• Human Intervention: Request human help for unsolvable captchas (ReCAPTCHA v2, hCaptcha)

• Detection: Identify captcha types on the page

Debugging

• Screenshots (full page or elements)

• Viewport control

• Performance metrics

• Element highlighting

Installation

pip install pypen-mcp

Or install from source:

git clone https://github.com/your-repo/pypen-mcp
cd pypen-mcp
pip install -e .

Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "pypen": {
      "command": "pypen-mcp"
    }
  }
}

For development:

{
  "mcpServers": {
    "pypen": {
      "command": "/path/to/pypen-mcp/.venv/bin/pypen-mcp"
    }
  }
}

Usage Examples

Basic Browser Automation

# Launch browser
browser_launch(headless=True)

# Navigate to target
browser_navigate(url="https://example.com")

# Extract page content
dom_get_source()

# Find and interact with elements
dom_find_element(css_selector="#username")
dom_type(selector="#username", text="admin")
dom_click(selector="button[type=submit]")

# Take screenshot for documentation
debug_screenshot(path="/tmp/screenshot.png")

# Close when done
browser_close()

Network Monitoring

# Enable traffic capture
network_enable_monitoring()

# Navigate and capture
browser_navigate(url="https://api.example.com")

# Get captured requests
network_get_logs(filter_url="/api/")

# Get response body for specific request
network_get_response_body(request_id="abc123")

# Disable when done
network_disable_monitoring()

Request Interception

# Set up interception rules
network_setup_handler(
    block_patterns=["analytics", "tracking", "ads"],
    modify_headers={"Authorization": "Bearer token123"},
    mock_responses={"/api/config": {"status": 200, "body": {"debug": true}}}
)

# Navigate with interception active
browser_navigate(url="https://example.com")

Session-Based Requests

# Login via UI (handles complex auth)
browser_navigate(url="https://app.com/login")
dom_type(selector="#email", text="user@example.com")
dom_type(selector="#password", text="password123")
dom_click(selector="button[type=submit]")

# Make authenticated API calls
session_make_request(
    url="https://app.com/api/user/profile",
    method="GET"
)

Captcha Handling

# Enable automatic Turnstile bypass
captcha_enable_turnstile_bypass(time_to_wait_captcha=10.0)

# Navigate to protected site
browser_navigate(url="https://protected-site.com")

# Wait for captcha processing
# ... automation continues ...

# For unsolvable captchas, request human help
captcha_detect_type()  # Check what's on page
captcha_request_human_intervention(
    captcha_type="recaptcha_v2",
    message="Please solve the ReCAPTCHA to continue"
)

# Wait for human to solve
captcha_wait_for_resolution(request_id="abc123", timeout=300)

Tool Reference

Browser Tools

Network Tools

DOM Tools

JavaScript Tools

Session Tools

Captcha Tools

Debug Tools

Important Notes

Browser Session Persistence

• The browser session persists until explicitly closed with browser_close

• All operations (DOM, JS, network) use the same active session

• Cookies and session state are maintained across navigations

Captcha Success Factors

Turnstile bypass success depends on:

1. IP Reputation: Use residential proxies with good reputation

2. Browser Fingerprint: Configure realistic browser options

3. Behavioral Patterns: Add realistic delays and interactions

Human Intervention Workflow

1. Detect captcha: captcha_detect_type()

2. Try auto-handling: captcha_handle_auto()

3. If fails, request help: captcha_request_human_intervention()

4. Wait for resolution: captcha_wait_for_resolution()

5. Continue automation

License

MIT