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

| Tool | Description | |------|-------------| | browser_launch | Launch browser with options (headless, proxy, etc.) | | browser_close | Close the browser instance | | browser_navigate | Navigate to a URL | | browser_go_back | Navigate back in history | | browser_go_forward | Navigate forward in history | | browser_refresh | Refresh current page | | browser_get_info | Get current URL and title |

Network Tools

| Tool | Description | |------|-------------| | network_enable_monitoring | Start capturing HTTP traffic | | network_disable_monitoring | Stop traffic capture | | network_get_logs | Get captured requests (with optional filter) | | network_get_response_body | Get response body for a request | | network_enable_interception | Enable request interception | | network_disable_interception | Disable interception | | network_setup_handler | Configure auto interception rules |

DOM Tools

| Tool | Description | |------|-------------| | dom_find_element | Find element by selector | | dom_find_elements | Find multiple elements | | dom_get_text | Get element text content | | dom_get_html | Get element HTML | | dom_click | Click an element | | dom_type | Type text into input | | dom_scroll | Scroll the page | | dom_get_source | Get full page HTML | | dom_wait_for | Wait for element to appear |

JavaScript Tools

| Tool | Description | |------|-------------| | js_execute | Execute JavaScript code | | js_get_console_logs | Get console logs | | js_get_global_vars | Extract global variables | | js_get_local_storage | Get localStorage data | | js_get_session_storage | Get sessionStorage data | | js_set_local_storage | Set localStorage value | | js_get_forms | Get all forms with inputs | | js_get_links | Get all links on page |

Session Tools

| Tool | Description | |------|-------------| | session_get_cookies | Get all cookies | | session_get_cookie | Get specific cookie | | session_set_cookie | Set a cookie | | session_delete_cookie | Delete a cookie | | session_clear_cookies | Clear all cookies | | session_export_cookies | Export cookies (json/netscape/header) | | session_import_cookies | Import cookies from JSON | | session_make_request | Make session-authenticated HTTP request |

Captcha Tools

| Tool | Description | |------|-------------| | captcha_enable_turnstile_bypass | Enable auto Turnstile handling | | captcha_disable_turnstile_bypass | Disable Turnstile handling | | captcha_detect_type | Detect captcha type on page | | captcha_handle_auto | Auto-handle detected captcha | | captcha_request_human_intervention | Request human help | | captcha_get_pending_interventions | Get unresolved requests | | captcha_resolve_intervention | Mark intervention as resolved | | captcha_wait_for_resolution | Wait for human to solve |

Debug Tools

| Tool | Description | |------|-------------| | debug_screenshot | Take page screenshot | | debug_get_viewport | Get viewport size | | debug_set_viewport | Set viewport size | | debug_get_performance | Get performance metrics | | debug_highlight | Highlight matching elements |

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