# 🦊 Camoufox MCP **Anti-detection browser automation for AI agents** [![npm version](https://img.shields.io/npm/v/camoufox-mcp.svg)](https://npmjs.org/package/camoufox-mcp) [![npm downloads](https://img.shields.io/npm/dm/camoufox-mcp.svg)](https://npmjs.org/package/camoufox-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/) MCP server for browser automation using [Camoufox](https://camoufox.com/) - an anti-detection Firefox browser.
## Installation ```bash npx camoufox-mcp ``` ## Claude Desktop Configuration Add to `claude_desktop_config.json`: **Basic:** ```json { "mcpServers": { "camoufox": { "command": "npx", "args": ["camoufox-mcp"] } } } ``` **With Proxy (via env vars):** ```json { "mcpServers": { "camoufox": { "command": "npx", "args": ["camoufox-mcp"], "env": { "PROXY_SERVER": "http://1.2.3.4:8080", "PROXY_USER": "username", "PROXY_PASS": "password" } } } } ``` Then in `~/.config/camoufox-mcp/settings.json`: ```json { "proxy": { "enabled": true, "server": "${PROXY_SERVER}", "username": "${PROXY_USER}", "password": "${PROXY_PASS}", "geoip": true } } ``` ## Why Camoufox MCP? | Feature | Camoufox MCP | Chrome DevTools MCP | |---------|--------------|---------------------| | **Anti-Detection** | | | | Bot detection bypass | ✅ Built-in | ❌ Detected | | Fingerprint randomization | ✅ | ❌ | | WebRTC leak protection | ✅ | ❌ | | Canvas fingerprint spoofing | ✅ | ❌ | | **Automation** | | | | Humanized cursor movement | ✅ Realistic paths | ❌ Instant jumps | | Click with human-like delays | ✅ | ❌ | | Proxy with GeoIP auto-config | ✅ Timezone/locale | ❌ Manual | | **JavaScript Evaluation** | | | | MainWorld eval (`__NUXT__`, `__NEXT_DATA__`) | ✅ | ✅ | | Isolated eval (async/await) | ✅ | ✅ | | **Session Management** | | | | Isolated browser sessions | ✅ Multiple contexts | ❌ Single context | | Pre-authenticated sessions | ✅ Cookie/localStorage injection | ❌ | | Session state export | ✅ Save to JSON | ❌ | | **Features** | | | | Cookie popup auto-dismiss | ✅ 50+ selectors | ❌ | | User action recording | ✅ | ❌ | | Network interception | ✅ | ✅ | | Console capture | ✅ | ✅ | | Performance tracing | ❌ | ✅ | | **Browser** | | | | Engine | Firefox (Gecko) | Chrome (Chromium) | | Auto-install | ✅ ~150MB | ✅ | ## Tools ### Session Management Sessions provide isolated browser contexts — each session has its own cookies, localStorage, and cache. Use sessions to run multiple authenticated profiles simultaneously. | Tool | Description | |------|-------------| | `create_session` | Create a new isolated session, optionally pre-loading cookies/localStorage from a JSON file | | `list_sessions` | List all sessions with their page counts and metadata | | `save_session` | Export a session's cookies and localStorage to a JSON file | | `close_session` | Close a session and all its pages | | `list_context_files` | List available context files registered in settings | ### Page Management | Tool | Description | |------|-------------| | `new_page` | Create a new page, optionally in a specific session | | `list_pages` | List all open pages with their session IDs | | `select_page` | Set a page as active | | `close_page` | Close a page | ### Navigation & Interaction | Tool | Description | |------|-------------| | `navigate_page` | Navigate to URL, back, forward, or reload | | `click` | Click an element by UID | | `hover` | Hover over an element | | `fill` | Fill a form field | | `fill_form` | Fill multiple form fields at once | | `press_key` | Press a key or key combination | | `drag` | Drag an element to another | ### Inspection | Tool | Description | |------|-------------| | `take_snapshot` | Text snapshot with interactive element UIDs | | `take_screenshot` | Screenshot of page or element | | `get_page_text` | Extract text content | | `evaluate_mainworld` | Run JS in page context (sync only) | | `evaluate_isolated` | Run JS in isolated context (async OK) | | `get_framework_state` | Extract Next.js/Nuxt.js state | ### Context Injection | Tool | Description | |------|-------------| | `inject_context` | Inject cookies + localStorage from a JSON file into a session | ### Monitoring | Tool | Description | |------|-------------| | `start_network_capture` / `stop_network_capture` | Capture network requests | | `get_network_logs` / `clear_network_logs` | View/clear captured requests | | `intercept_network` / `remove_intercept` | Block or modify requests | | `start_console_capture` / `stop_console_capture` | Capture console messages | | `get_console_logs` / `clear_console_logs` | View/clear console messages | | `start_recording` / `stop_recording` / `get_recording_status` | Record user interactions | ### Utility | Tool | Description | |------|-------------| | `dismiss_popups` | Auto-dismiss cookie consent popups | | `wait_for` | Wait for text or selector | | `wait_for_navigation` | Wait for navigation to complete | | `reload_settings` | Reload settings from config | | `get_config_paths` | Show config file paths | | `init_user_config` | Initialize user config directory | ## Sessions Sessions enable running multiple authenticated profiles in parallel. Each session is an isolated browser context with its own cookies and localStorage. ``` Browser (single Camoufox instance) ├── Session "github" (cookies from github.json) │ ├── Page: github.com │ └── Page: github.com/repo ├── Session "linkedin" (cookies from linkedin.json) │ └── Page: linkedin.com/feed └── Session "default" (no pre-loaded state) └── Page: example.com ``` ### Usage Examples **Create a session with pre-loaded authentication:** 1. `create_session` with `contextPath: "github-cookies.json"` — returns a `sessionId` 2. `new_page` with `url: "https://github.com"` and the `sessionId` — opens GitHub already logged in **Run two accounts simultaneously:** 1. `create_session` with `contextPath: "account1.json"` — session A 2. `create_session` with `contextPath: "account2.json"` — session B 3. `new_page` in session A — logged in as account 1 4. `new_page` in session B — logged in as account 2 **Save session state for later:** 1. Log in manually in a session 2. `save_session` with `outputPath: "my-session.json"` — exports cookies + localStorage 3. Next time, `create_session` with `contextPath: "my-session.json"` — restored ### Context File Format Context files use [Playwright's storageState format](https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state): ```json { "cookies": [ { "name": "session_id", "value": "abc123", "domain": ".example.com", "path": "/", "expires": 1735689600, "httpOnly": true, "secure": true, "sameSite": "Lax" } ], "origins": [ { "origin": "https://example.com", "localStorage": [ { "name": "token", "value": "xyz789" } ] } ] } ``` ### Registering Context Files in Settings Add context file paths to `settings.json` to make them discoverable via `list_context_files`. Sessions are created **lazily on demand** — no memory is used until the agent calls `create_session`: ```json { "contextPaths": [ "/path/to/github-cookies.json", "/path/to/linkedin-cookies.json" ] } ``` The agent can then call `list_context_files` to see what's available, and `create_session` with the desired `contextPath` to load it when needed. ## Settings Create `~/.config/camoufox-mcp/settings.json`: ```json { "browser": { "headless": false, "viewport": [1280, 1080], "timeout": 30000, "humanize": 0.5 }, "proxy": { "enabled": true, "server": "http://proxy.example.com:8080", "username": "user", "password": "pass", "geoip": true }, "contextPaths": [] } ``` ### Proxy Examples **HTTP/HTTPS Proxy:** ```json { "proxy": { "enabled": true, "server": "http://1.2.3.4:8080" } } ``` **SOCKS5 Proxy:** ```json { "proxy": { "enabled": true, "server": "socks5://1.2.3.4:1080" } } ``` **With Authentication (using env vars):** ```json { "proxy": { "enabled": true, "server": "${PROXY_SERVER}", "username": "${PROXY_USER}", "password": "${PROXY_PASS}", "geoip": true } } ``` > `geoip: true` auto-adjusts browser timezone/locale based on proxy IP location. ## See More - [Camoufox](https://github.com/daijro/camoufox) - The anti-detection Firefox browser - [camoufox-js](https://github.com/AnyFetch/camoufox-js) - JavaScript/TypeScript bindings ## License MIT