camoufox-mcp-python 0.3.0

Camoufox-powered MCP browser server with ref-based accessibility tools.

camoufox-mcp-python

中文文档

A Model Context Protocol (MCP) server that provides browser automation tools powered by Camoufox — a stealthy, anti-detect browser built on Firefox. It exposes a Playwright-MCP compatible tool interface using accessibility snapshots and ref-based element targeting.

Think of it as playwright-mcp, but with built-in anti-detection and fingerprint spoofing.

Features

• Anti-detect browser fingerprinting — Camoufox automatically spoofs browser fingerprints to bypass bot detection
• Ref-based accessibility snapshots — Interact with page elements via accessibility refs, no CSS selectors needed
• Human-like cursor movement — Cursor humanization enabled by default for realistic interactions
• WebRTC leak protection — WebRTC blocked by default to prevent IP leaks
• Isolated browser profiles by default — Each server process gets a fresh temporary profile that is deleted on close; pass --user-data-dir to reuse a persistent profile
• GeoIP auto-matching — Automatically match browser locale/timezone to proxy location
• Proxy support — Full proxy support including authentication
• WebGL fingerprint control — Specify WebGL vendor/renderer pair or block entirely
• Custom addons — Load custom Firefox addons or exclude defaults like uBlock Origin
• Advanced fingerprint config — Override any BrowserForge fingerprint property or use a custom fingerprint
• Firefox preferences — Set custom Firefox user preferences
• Browser caching — Optional page/request caching for performance
• Privacy controls — Block WebGL and image loading to reduce leaks and bandwidth
• Multi-tab management — Create, close, select, and list browser tabs
• Modal & dialog handling — Handle JavaScript dialogs and file choosers
• Console & network monitoring — Inspect console messages and network requests

Quick Start

Use with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "camoufox": {
      "command": "uvx",
      "args": ["camoufox-mcp-python"]
    }
  }
}

Use with Claude Code

claude mcp add camoufox -- uvx camoufox-mcp-python

Use with VS Code / Cursor

Add to .vscode/mcp.json:

{
  "servers": {
    "camoufox": {
      "command": "uvx",
      "args": ["camoufox-mcp-python"]
    }
  }
}

Use with Codex CLI

Add to codex.json or pass via CLI:

codex --mcp-server "npx @anthropic-ai/mcp-proxy -- uvx camoufox-mcp-python"

Pin a specific version

{
  "mcpServers": {
    "camoufox": {
      "command": "uvx",
      "args": ["--from", "camoufox-mcp-python==0.2.1", "camoufox-mcp-python"]
    }
  }
}

CLI Options

Option	Description
--headless / --no-headless	Run the browser headlessly (default: on)
--proxy <url>	Proxy server URL (supports user:pass@host:port)
--os <os>	Target OS fingerprint: windows, macos, linux (repeatable)
--humanize [seconds]	Cursor humanization (default: on). Pass a number for max duration, or false to disable
--geoip [ip]	Auto-match locale/timezone to proxy IP, or specify a target IP
--locale <locale>	Browser locale(s), e.g. en-US (repeatable, comma-separated)
--window <WxH>	Outer window size, e.g. 1280x720
--block-webrtc / --no-block-webrtc	Block WebRTC to prevent IP leaks (default: on)
--block-webgl	Disable WebGL
--block-images	Block image requests to reduce bandwidth
--disable-coop	Disable COOP for cross-origin iframe interactions
--user-data-dir <path>	Optional persistent profile directory. If omitted, each server process uses an isolated temporary profile that is deleted on close
--caps <groups>	Enable capability groups, e.g. dangerous (enables browser_evaluate)
--webgl-config <v,r>	WebGL vendor/renderer pair, e.g. "Intel Inc.,Intel(R) UHD Graphics 620"
--addons <paths>	Paths to extracted Firefox addons (repeatable, comma-separated)
--exclude-addons <names>	Default addons to exclude, e.g. UBO (repeatable, comma-separated)
--config <json>	Camoufox fingerprint properties as a JSON string
--enable-cache	Cache previous pages and requests (uses more memory)
--firefox-user-prefs <json>	Firefox user preferences as a JSON string
--i-know-what-im-doing	Silence Camoufox warnings for advanced configurations
--debug	Print the config being sent to Camoufox

Examples

# Zero-config anti-detection (headless + humanize + block-webrtc on by default)
camoufox-mcp-python

# With proxy and GeoIP matching
camoufox-mcp-python --proxy http://user:[e-mail]:8080 --geoip

# Visible browser for debugging
camoufox-mcp-python --no-headless --debug

# Custom WebGL fingerprint
camoufox-mcp-python --webgl-config "Intel Inc.,Intel(R) UHD Graphics 620" --os windows

# Custom fingerprint properties
camoufox-mcp-python --config '{"navigator.hardwareConcurrency": 8}'

# With caching and custom Firefox prefs
camoufox-mcp-python --enable-cache --firefox-user-prefs '{"dom.webnotifications.enabled": false}'

# Privacy-hardened mode
camoufox-mcp-python --block-webgl --block-images

# Disable default anti-detection for debugging
camoufox-mcp-python --no-headless --humanize false --no-block-webrtc --debug

# Enable JavaScript evaluation
camoufox-mcp-python --caps dangerous

Available Tools

Navigation

Tool	Description
browser_navigate	Navigate to a URL
browser_navigate_back	Go back to the previous page

Snapshot & Interaction

Tool	Description
browser_snapshot	Capture an accessibility snapshot of the current page
browser_click	Click an element by ref (supports double-click, right-click, modifiers)
browser_hover	Hover over an element
browser_drag	Drag from one element to another
browser_select_option	Select option(s) in a dropdown

Input

Tool	Description
browser_type	Type text into an editable element (supports slow typing and submit)
browser_press_key	Press a keyboard key or key combination
browser_fill_form	Fill multiple form fields in a single call

Page

Tool	Description
browser_take_screenshot	Take a screenshot (viewport, full page, or element)
browser_console_messages	Retrieve collected console messages
browser_network_requests	List network requests seen by the page
browser_resize	Resize the viewport
browser_wait_for	Wait for text to appear/disappear, or a fixed duration
browser_close	Close the browser session

Tabs

Tool	Description
browser_tabs	List, create, close, or select browser tabs

Modals & Files

Tool	Description
browser_handle_dialog	Accept or dismiss a JavaScript dialog
browser_file_upload	Handle a file chooser and upload files

Dangerous (requires --caps dangerous)

Tool	Description
browser_evaluate	Execute arbitrary JavaScript on the page or an element

How It Works

The server uses Camoufox (a Firefox-based anti-detect browser) through Playwright's async API. Pages are represented as accessibility snapshots in YAML format, where each interactive element is assigned a ref identifier. The AI model reads the snapshot, identifies the target ref, and calls the appropriate tool — no fragile CSS/XPath selectors required.

AI Model  ←→  MCP Server  ←→  Camoufox Browser
                  │
                  ├── Accessibility Snapshot (YAML)
                  ├── Ref-based element targeting
                  └── Anti-detect fingerprinting

Local Development

# Clone and install
git clone https://github.com/user/camoufox-mcp.git
cd camoufox-mcp
uv pip install --python .venv/bin/python -e .

# Run the server
./.venv/bin/camoufox-mcp-python --headless

# Or run as a module
./.venv/bin/python -m camoufox_mcp --headless

# Smoke test
./.venv/bin/python -m compileall camoufox_mcp
./.venv/bin/camoufox-mcp-python --help

Requirements

• Python >= 3.10
• camoufox >= 0.4.11
• mcp[cli] >= 1.25
• playwright >= 1.58

Note: The first launch on a new machine may trigger automatic Camoufox binary and addon downloads.

License

MIT