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](https://github.com/anthropics/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

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:[email protected]: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

Snapshot & Interaction

Input

Page

Tabs

Modals & Files

Dangerous (requires --caps dangerous)

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