Camoufox Unified MCP Server

English | 中文

Model Context Protocol (MCP) server for stealth browser automation and anti-detection web interaction, powered by the Camoufox modified Firefox Gecko engine.

1. Project Overview

The Camoufox Unified MCP Server provides AI agents with a standardized, protocol-level interface to execute browser automation under strict anti-bot and Web Application Firewall (WAF) environments.

By integrating the architectural paradigms of community implementations, this project synthesizes:

1. Enterprise-grade session lifecycle management, including state serialization (Cookies and LocalStorage) and automated cookie consent banner dismissal, pioneered in the Node.js implementation by baixianger.

2. Comprehensive atomic browser controls and Python-native asynchronous execution pipelines, demonstrated in the Python CLI and MCP implementations by rlgrpe.

This unified server is engineered entirely in Python on top of the Model Context Protocol SDK and the official Camoufox browser library by daijro.

2. Technical Architecture

2.1 Gecko Engine-Level Anti-Fingerprinting

Standard automation frameworks (e.g., standard Playwright or Puppeteer on Chromium) operate via JavaScript prototype shims or CDP flags that remain vulnerable to runtime detection:

• Prototype pollution probes (e.g., inspecting Object.getOwnPropertyDescriptor on navigator properties).

• Chromium-specific leaks (e.g., window.chrome, Blink rendering memory artifacts, V8 stack trace anomalies).

• Automated TLS/JA3/JA4 fingerprinting designed specifically to flag automated Chromium clients.

Camoufox resolves these vulnerabilities at the C++ source level within the Mozilla Firefox (Gecko) engine:

• Hardware and platform virtualization: Native spoofing of hardwareConcurrency, deviceMemory, screen dimensions, color depth, and system fonts without JavaScript runtime overhead.

• Canvas, WebGL, and AudioContext noise injection: Deterministic or randomized mathematical jitter applied directly within the graphics and audio rendering pipelines.

• Native Firefox TLS/HTTP2 stack: Inherits genuine Firefox network signatures, circumventing anti-bot algorithms that target Chromium automation headers.

2.2 Asynchronous Architecture and Concurrency Model

The server uses FastMCP over standard I/O (stdio) transport:

• State Synchronization: A singleton CamoufoxManager coordinates browser processes using asyncio.Lock, ensuring thread safety across concurrent tool invocations.

• Lazy Initialization: The browser process is not spawned at server startup. Resources are allocated only upon the first invocation requiring browser interaction, conserving memory during inactive periods.

• Dual-Mode Session Isolation: Supports independent BrowserContext instances per session identifier. Each session operates with discrete cache directories, cookie stores, and LocalStorage databases.

2.3 State Serialization Pipeline

Session persistence utilizes Playwright Storage State specifications:

• Data Schema: Serializes all active session cookies (including secure, httpOnly, and SameSite attributes) alongside origins-level LocalStorage key-value pairs into structured JSON representations.

• Portability: Serialized states can be saved to disk, transferred across environments, and injected into newly instantiated BrowserContext instances prior to page navigation, bypassing redundant authentication flows.

2.4 Humanized Behavioral Simulation

To defeat behavioral analysis heuristics (e.g., Cloudflare Turnstile, DataDome mouse tracking):

• Cursor Trajectories: Mouse movements follow cubic Bezier curves with randomized control points, velocity variance, and simulated overshoot rather than linear or instantaneous coordinate jumps.

• Keystroke Timing: Text input simulates human typing cadence using randomized Gaussian intervals per character, including micro-delays between words.

• Smooth Scrolling: Wheel events are segmented into incremental step bursts with decaying velocity.

2.5 Heuristic Consent Banner Dismissal

An automated banner resolution subsystem scans active pages against a priority matrix of known consent management platforms:

• Vendor Selectors: OneTrust, Cookiebot, Klaro, TrustArc, and Osano.

• Heuristic Selectors: Generalized attribute matching for button elements containing consent-related identifiers across multiple language encodings (English, Simplified Chinese, Traditional Chinese).

3. Tool Reference

The server exposes 19 discrete tools grouped into functional subsystems:

3.1 Session and Authentication Tools

3.2 Navigation and Tab Control Tools

3.3 Humanized Interaction Tools

3.4 Extraction and Execution Tools

3.5 Anti-Detection Diagnostics Tools

4. Installation and Setup

4.1 System Prerequisites

• Python 3.10 or later.

• uv package manager (recommended) or standard pip.

• Supported operating systems: Windows, macOS, Linux.

4.2 Installation via UV (Recommended)

1. Clone or download the repository:

git clone https://github.com/tom613951/camoufox-unified-mcp.git
cd camoufox-unified-mcp

2. Create an isolated virtual environment:

uv venv .venv

3. Install project dependencies:

uv pip install -e .

4. Fetch the pre-compiled Camoufox Firefox browser binary:

uv run camoufox fetch

4.3 Installation via Pip

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .
camoufox fetch

5. Client Configuration

Configure the MCP server within your AI client settings file.

5.1 Claude Desktop Configuration

File path:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "camoufox": {
      "command": "path/to/camoufox-unified-mcp/.venv/bin/python",
      "args": [
        "path/to/camoufox-unified-mcp/run_mcp.py"
      ]
    }
  }
}

Windows example:

{
  "mcpServers": {
    "camoufox": {
      "command": "D:\\skills-mcp\\camoufox-unified-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "D:\\skills-mcp\\camoufox-unified-mcp\\run_mcp.py"
      ]
    }
  }
}

5.2 Antigravity / Gemini CLI Configuration

File path: ~/.gemini/config/mcp_config.json

{
  "mcpServers": {
    "camoufox": {
      "command": "D:\\skills-mcp\\camoufox-unified-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "D:\\skills-mcp\\camoufox-unified-mcp\\run_mcp.py"
      ]
    }
  }
}

5.3 Cursor Configuration

In Cursor Settings -> Features -> MCP -> Add New MCP Server:

• Name: camoufox

• Type: command

• Command: D:\skills-mcp\camoufox-unified-mcp\.venv\Scripts\python.exe D:\skills-mcp\camoufox-unified-mcp\run_mcp.py

6. Acknowledgements

This unified project builds upon and synthesizes the foundational contributions of open-source developers:

• daijro (Author of daijro/camoufox): For engineering the customized, anti-detection Firefox Gecko engine, automated binary packaging, and the Python library bindings that serve as the foundational runtime for this project.

• baixianger (Author of baixianger/camoufox-mcp): For pioneering the MCP session lifecycle architecture, storage state persistence patterns, heuristic consent banner resolution, and high-level agent integration concepts in Node.js.

• rlgrpe (Author of rlgrpe/camoufox-browser-cli): For designing the Python FastMCP implementation paradigms, fine-grained atomic browser tool definitions, and lazy resource allocation patterns.

7. License

This project is licensed under the terms of the MIT License. See the LICENSE file for details.