Camoufox MCP

Stealth browser automation MCP server powered by Camoufox — a humanized Playwright Firefox fork. Playwright MCP quality with two-tier Cloudflare bypass, headed-mode viewport/window alignment, CSS selector + snapshot ref targeting, batch form filling, drag & drop, async JS evaluation, keyboard input, console capture, tab management, cookies, file upload, and annotated screenshots.

Features

• Stealth by default — randomized viewports, real human mouse/keyboard patterns, spoofed fingerprints
• Headed mode that matches what you see — launch-time Camoufox fingerprint window is aligned with the Playwright viewport so Retina/macOS pages do not render off-screen or look zoomed/clipped
• Two-tier Cloudflare bypass — cloudscraper (fast HTTP) → FlareSolverr (guaranteed, with browser recovery)
• Full browser session recovery — flaresolverr_solve sets up Playwright route interception so the entire browser session works through FlareSolverr: navigate, snapshot, click, type — all transparent
• Ref-based interaction — snapshot-first: [@eN] refs from accessibility tree with real CSS selectors; click by ref, type by ref. Also accepts raw CSS selectors for elements not in the snapshot (React portals, popovers, etc.).
• Batch form filling — camoufox_fill_form fills multiple fields at once (textbox, checkbox, radio, combobox, slider).
• Drag & drop — camoufox_drag moves elements between targets.
• Async JavaScript — camoufox_evaluate supports both sync and async expressions with configurable timeout.
• Tab management — open multiple pages, switch between them, close individually
• Console capture — real-time JS errors, warnings, and logs from the page
• Auto-managed FlareSolverr — Tier 2 automatically starts/stops Docker container on demand
• Persistent sessions — cookies survive restarts via user_data_dir
• Proxy support — residential proxies for harder targets
• trafilatura integration — production-grade readability extraction when available

Quick Start

pip install camoufox-mcp
# With better markdown extraction:
pip install camoufox-mcp[extract]
camoufox-mcp

Or add to your MCP client config (claude_desktop_config.json, etc.):

"camoufox-mcp": {
  "command": "camoufox-mcp"
}

Tier 2: FlareSolverr (for hardest Cloudflare)

Tier 2 uses FlareSolverr (Docker-based headless Chromium) to bypass Turnstile, JS VM v3, and CAPTCHA challenges. The MCP server manages it automatically — it starts on first use, stops when you're done. Just have Docker installed.

# Only need Docker installed. The MCP server handles everything else.
# First Tier 2 call auto-pulls the image and starts the container.

Tools (39 total)

Browser Lifecycle

Tool	Description
camoufox_launch	Start stealth browser (Firefox-based Playwright)
camoufox_resize_viewport	Resize viewport; in headed mode, relaunches Camoufox with matching fingerprint window and restores cookies/URLs
camoufox_close	Close browser and release all resources

Page / Tab Management

Tool	Description
camoufox_new_page	Open a new tab (becomes active)
camoufox_close_page	Close a specific tab
camoufox_list_pages	List all open pages with URLs and active status

Navigation

Tool	Description
camoufox_navigate	Navigate to URL — flags cloudflare_blocked if CF detected
camoufox_back	Navigate back in browser history

Page Interaction

Tool	Description
camoufox_snapshot	Get interactive elements as [@eN] refs with real CSS selectors. Detects React portals / popovers.
camoufox_click	Click by ref or raw CSS selector (supports double-click)
camoufox_type	Type text into input by ref or raw CSS selector
camoufox_fill_form	Batch fill multiple fields at once (textbox, checkbox, radio, combobox, slider)
camoufox_drag	Drag one element onto another by ref or CSS selector
camoufox_press	Press keyboard key (Enter, Tab, Escape, ArrowDown, etc.)
camoufox_select	Select dropdown option by value/label/index. Accepts ref or CSS selector.
camoufox_hover	Hover over element by ref or CSS selector
camoufox_scroll	Scroll up/down by pixel amount
camoufox_evaluate	Execute JavaScript in page context (sync or async, configurable timeout)
camoufox_file_upload	Upload files to a file input by ref or CSS selector
camoufox_wait	Wait for page to settle (network idle)

Content Extraction

Tool	Description
camoufox_read_page	Extract page as clean markdown (trafilatura when available)
camoufox_screenshot	Take screenshot (optional annotated element overlays)
camoufox_get_dialogs	Get captured JS dialogs (alert/confirm/prompt) — auto-dismissed
camoufox_console	Get browser console messages (JS errors, warnings, logs)

Cookie Management

Tool	Description
camoufox_get_cookies	Get all browser cookies (optional URL filter)
camoufox_set_cookies	Set cookies from JSON array
camoufox_clear_cookies	Clear all cookies

Bug Bounty / API Tools

Tool	Description
camoufox_extract_tokens	Grab JWT, CSRF, cookies from session (generic, any web app)
camoufox_api_call	Make authenticated API call using browser session (auto-detect CSRF)
camoufox_js_extract	Find endpoints/secrets in loaded JavaScript bundles
camoufox_network_capture	Capture XHR/fetch traffic for API endpoint discovery

Cloudflare Bypass — Two Tiers

Tier	Tool	Speed	What it does
1	camoufox_cloudscraper_fetch	~100-500ms	HTTP-level JS solver: IUAM, JS v1, JS v2
	camoufox_cloudscraper_solve	~1-2s	Cookie injection into browser
2	camoufox_flaresolverr_fetch	~1-15s	Turnstile, JS VM v3, CAPTCHA — returns content + links
	camoufox_flaresolverr_solve	~1-15s	Full browser recovery via route interception — browser works normally after

Tool	Description
camoufox_flaresolverr_start	Start FlareSolverr Docker container
camoufox_flaresolverr_stop	Stop FlareSolverr container
camoufox_flaresolverr_health	Check if FlareSolverr is running

Headed Mode Viewport Alignment

Camoufox spoofs browser fingerprint values such as window.innerWidth and window.outerWidth. In headed mode, Camoufox MCP now keeps that spoofed fingerprint window aligned with Playwright's viewport so visually centered pages, OAuth/login screens, and responsive layouts render where the user actually sees them.

# Launch a comfortable headed browser for manual login / visual QA
camoufox_launch(
    display_mode="headed",
    viewport_width=1280,
    viewport_height=800,
)

# Auto-fit to the detected screen on macOS, or pass explicit dimensions
camoufox_resize_viewport(width=0, height=0)
camoufox_resize_viewport(width=1440, height=900)

In headed mode, camoufox_resize_viewport relaunches Camoufox with a matching fingerprint window and restores cookies, storage state, open page URLs, and the active page id. In headless mode, it performs a normal Playwright viewport resize.

Cloudflare Bypass Workflow

When camoufox_navigate returns cloudflare_blocked: true:

Fetch content only (fast, no browser needed)

flaresolverr_fetch(url) → content + links array
  Returns a 'links' array for directory discovery (supports <a href> and phx-click).

Full browser session recovery (the browser works normally after)

navigate → cf_blocked
  → flaresolverr_solve(page_id) → routes_active: true
  → navigate (same URL) → page loads!  ← CF bypassed transparently
  → snapshot / click / type / read_page — all work normally

How it works:
  flaresolverr_solve sets up Playwright route interception — ALL document/xhr/fetch requests
  to the CF-protected domain are proxied through FlareSolverr's headless
  Chromium (which has CF clearance). Subresources load directly for speed.
  The browser renders normally — no tools behave differently.

Example

# Navigate to a hard target
result = camoufox_navigate("page_abc", "https://vx-underground.org/")

if result.get("cloudflare_blocked"):
    # Recover full browser session — routes ALL requests through FlareSolverr
    camoufox_flaresolverr_solve(page_id="page_abc")

    # Now navigate normally — FlareSolverr handles CF transparently
    camoufox_navigate("page_abc", "https://vx-underground.org/")
    # → cloudflare_blocked: false, title: "Vx Underground"

    # All normal tools work:
    camoufox_snapshot("page_abc")     # Interactive elements with [@eN] refs
    camoufox_read_page("page_abc")    # Full content as markdown
    camoufox_click("page_abc", "@e8") # Click file entries
    camoufox_scroll("page_abc")       # Scroll normally

Architecture

camoufox-mcp/
├── camoufoxmcp/
│   ├── __init__.py              # v0.7.0
│   ├── __main__.py              # Entry point
│   ├── server.py                # FastMCP server + 39 tool definitions
│   ├── session.py               # BrowserSession: lifecycle, dialogs, console, cookies, tabs
│   ├── snapshot.py              # Accessibility-tree snapshot + CSS selector ref resolution
│   ├── markdown.py              # trafilatura + regex fallback markdown extraction
│   ├── vision.py                # Screenshots with optional element annotation overlays
│   ├── cloudscraper_bridge.py   # Tier 1: HTTP JS solver + cookie injection
│   └── flaresolverr_bridge.py   # Tier 2: solve, fetch (raw + text), links, Docker mgmt
├── pyproject.toml
└── tests/

Development

git clone https://github.com/overtimepog/camoufox-mcp.git
cd camoufox-mcp
pip install -e ".[dev,extract]"
pytest tests/

Why Camoufox over CloakBrowser?

	CloakBrowser	Camoufox
Engine	Source-patched Chromium	Humanized Playwright (Firefox/Chromium)
Cloudflare	Passes Turnstile/reCAPTCHA	Two-tier bypass: cloudscraper → FlareSolverr
CF auto-management	Manual cookie import	Auto-start/stop Docker FlareSolverr
Browser recovery	N/A	Route interception: flaresolverr_solve recovers the entire browsing session
Console capture	—	Real-time JS error/warning/log capture
Tab management	—	Multi-page with active tracking
Cookie management	—	Get/set/clear cookies programmatically
Markdown quality	—	trafilatura (production readability) + fallback
Maintenance	You maintain the fork	Active upstreams (askjoe, cloudscraper, FlareSolverr)
Platforms	Linux/Windows/macOS	Linux/Windows/macOS

License

Apache-2.0