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