🦊 Camoufox MCP Browser

A Model Context Protocol (MCP) server designed to provide stealthy web browsing capabilities (anti-detection) to AI agents using the Camoufox engine.

🚀 Goal

Enable AI agents (such as Claude, GPT, etc.) to interact with the modern web without being blocked, maintaining persistent sessions and allowing detailed visual and structural inspection of content.

✨ Key Features

• 🕵️ Advanced Stealth: Engine based on Camoufox (custom Firefox) with C++ level fingerprint spoofing.

• 🔗 Session Management: Hash-based system to maintain multiple independent and persistent navigation contexts.

• 📸 Dual Screenshots: Returns screenshots in Base64 directly to the agent and optionally saves them to local files.

• 🛠️ Interaction Tools: Navigation, clicks, text typing, scrolling, and link extraction.

• 🐳 Docker Native: Optimized container with all necessary system dependencies to run browsers in headless mode.

🛠️ Available Tools

📦 Installation and Usage

1. Requirements

• Docker and Docker Compose.

• Python 3.11+ (to run test scripts).

2. Deployment with Docker

# Clone and start
git clone https://github.com/danielmiranda/camoufox-browser-mcp.git
cd camoufox-browser-mcp
docker-compose up --build -d

3. Configuration in MCP Clients (e.g., Claude Desktop)

Add the following to your configuration file:

{
  "mcpServers": {
    "camoufox-browser": {
      "command": "docker",
      "args": ["exec", "-i", "camofox-mcp", "python", "src/mcp_server.py"]
    }
  }
}

🧪 Verification Tests

We have included example scripts to verify integration:

• General Test: python examples/test_mcp_docker.py (Simulates full agent flow).

• ScrapingBee Test: python examples/scrapingbee_test.py (Navigates, lists links, and performs clicks).

⚠️ Current Limitations

• Resource Consumption: Since it manages persistent sessions, memory usage can scale with many open tabs.

• Headless Mode: Some websites specifically detect headless rendering despite advanced spoofing (though Camoufox minimizes this).

• Network: Loading speed depends entirely on the Docker host's connectivity.

🗺️ Roadmap (Future)

• AI-Optimized Markdown: Tool to extract web content directly as Markdown (token saving).

• Accessibility Tree tools: Tools to interact based on accessibility roles instead of CSS selectors.

• Proxy Rotation: Integrated proxy management for each hashed session.

• Captcha Solving: Integration with captcha solving services for fully autonomous flows.

Built with ❤️ for the AI Agent community.