🦊 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

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.

Camoufox Browser MCP