Camoufox Browser

MCP Docker Python

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

Tool	Description
browser_navigate	Navigates to a URL and creates/reuses a persistent session.
browser_interact	Performs actions like click, type, scroll_up, scroll_down.
browser_get_markdown	Converts current page to Markdown for AI token efficiency.
browser_list_links	Extracts all links and their descriptive text from the current page.
browser_screenshot	Captures the current view (Base64 + optional file).
browser_snapshot	Retrieves the raw HTML content of the session.
browser_sessions	Lists the hashes of all active sessions.

📦 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.