README.md
Stealthy browser automation using a custom Firefox build for anti-detection.
🦊 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.
Tools (7)
browser_navigateNavigates to a URL and creates/reuses a persistent session.browser_interactPerforms actions like click, type, scroll_up, scroll_down.browser_get_markdownConverts current page to Markdown for AI token efficiency.browser_list_linksExtracts all links and their descriptive text from the current page.browser_screenshotCaptures the current view (Base64 + optional file).browser_snapshotRetrieves the raw HTML content of the session.browser_sessionsLists the hashes of all active sessions.Configuration
claude_desktop_config.json
{"mcpServers": {"camoufox-browser": {"command": "docker", "args": ["exec", "-i", "camofox-mcp", "python", "src/mcp_server.py"]}}}Try it
→Navigate to https://example.com and extract all the links on the page.
→Take a screenshot of the current page and save it to my local directory.
→Go to the login page, type my username and password into the fields, and click the submit button.
→Convert the current webpage content into clean Markdown format for me to read.
→List all my active browser sessions and switch to the one for my research project.