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:pass@proxy.example.com: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\]](https://github.com/modelcontextprotocol/python-sdk) >= 1.25
• playwright >= 1.58

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

License

MIT