{"id":44573135,"url":"https://github.com/redf0x1/camofox-mcp","last_synced_at":"2026-02-19T14:01:19.125Z","repository":{"id":338230380,"uuid":"1157099451","full_name":"redf0x1/camofox-mcp","owner":"redf0x1","description":"Anti-detection browser MCP server for AI agents — navigate, interact, and automate the web without getting blocked","archived":false,"fork":false,"pushed_at":"2026-02-16T13:05:28.000Z","size":140,"stargazers_count":18,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-02-17T15:17:03.844Z","etag":null,"topics":["ai-agent","anti-detection","automation","bot-detection","browser","browser-automation","camofox","camoufox","claude","cursor","fingerprint","headless-browser","llm","mcp","model-context-protocol","playwright-alternative","stealth-browser","typescript","vscode","web-scraping"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/redf0x1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-13T12:34:13.000Z","updated_at":"2026-02-17T04:20:03.000Z","dependencies_parsed_at":"2026-02-17T12:01:04.504Z","dependency_job_id":null,"html_url":"https://github.com/redf0x1/camofox-mcp","commit_stats":null,"previous_names":["redf0x1/camofox-mcp"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/redf0x1/camofox-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redf0x1%2Fcamofox-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redf0x1%2Fcamofox-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redf0x1%2Fcamofox-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redf0x1%2Fcamofox-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redf0x1","download_url":"https://codeload.github.com/redf0x1/camofox-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redf0x1%2Fcamofox-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29580622,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T08:38:15.585Z","status":"ssl_error","status_checked_at":"2026-02-18T08:38:14.917Z","response_time":162,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","anti-detection","automation","bot-detection","browser","browser-automation","camofox","camoufox","claude","cursor","fingerprint","headless-browser","llm","mcp","model-context-protocol","playwright-alternative","stealth-browser","typescript","vscode","web-scraping"],"created_at":"2026-02-14T03:56:44.574Z","updated_at":"2026-02-18T13:00:41.006Z","avatar_url":"https://github.com/redf0x1.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🦊 CamoFox MCP\n\n**The anti-detection browser MCP server for AI agents.** Navigate, interact, and automate the web without getting blocked.\n\n[![CI](https://github.com/redf0x1/camofox-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/redf0x1/camofox-mcp/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/camofox-mcp)](https://www.npmjs.com/package/camofox-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io/)\n\n\u003e **New to CamoFox?** Skip the docs — [paste this prompt](#3-verify-setup) into your AI agent and it’ll verify your setup end-to-end.\n\n**How it works (TL;DR)**\n\n```\nYour AI Agent ──(MCP)──\u003e camofox-mcp ──(REST)──\u003e camofox-browser ──\u003e Camoufox (anti-detection Firefox)\n```\n\nCamoFox has **2 components** — you need both running:\n\n- `camofox-browser` is the headless browser server (anti-detection)\n- `camofox-mcp` is the MCP bridge your AI agent connects to\n\n---\n\n## Why CamoFox MCP?\n\nAI agents using Playwright get **blocked constantly**. CAPTCHAs, fingerprint detection, IP bans — the web fights back against automation.\n\n**CamoFox MCP** wraps the [CamoFox Browser Server](https://github.com/redf0x1/camofox-browser) as an MCP server, giving your AI agent:\n\n- 🛡️ **Anti-detection fingerprinting** — Each tab gets a unique, human-like browser fingerprint\n- ⚡ **Fast, token-efficient snapshots** — Accessibility tree snapshots use 90% fewer tokens than screenshots\n- 🔍 **Built-in search** — Search Google, YouTube, Amazon + 11 more engines without getting blocked  \n- 🍪 **Session persistence** — Import cookies, maintain login state across interactions\n- 🎯 **CSS selector fallback** — Target elements even when accessibility refs aren't available\n\n### CamoFox MCP vs Playwright MCP\n\n| Feature | CamoFox MCP | Playwright MCP |\n|---------|:-----------:|:--------------:|\n| Anti-detection fingerprinting | ✅ | ❌ |\n| Passes bot detection tests | ✅ | ❌ |\n| Search engine macros (14 engines) | ✅ | ❌ |\n| Accessibility snapshots | ✅ | ✅ |\n| Cookie import/export | ✅ | Limited |\n| Headless support | ✅ | ✅ |\n| Setup complexity | Medium | Easy |\n| Token efficiency | High | High |\n\n### CamoFox MCP vs Other Camoufox MCPs\n\n| Feature | CamoFox MCP | whit3rabbit/camoufox-mcp | baixianger/camoufox-mcp |\n|---------|:-----------:|:-----------------------:|:-----------------------:|\n| Tools | 35 | 1 | 33 |\n| Architecture | REST API client | Direct browser | Direct browser |\n| Session persistence | ✅ | ❌ (destroyed per request) | ✅ |\n| Token efficiency | High (snapshots) | Low (raw HTML) | High (snapshots) |\n| Search macros | ✅ (14 engines) | ❌ | ❌ |\n| CSS selector fallback | ✅ | ❌ | ❌ |\n| Active maintenance | ✅ | ❌ (stale 8mo) | ✅ |\n| Press key support | ✅ | ❌ | ✅ |\n\n## Prerequisites\n\n- **Pick one:**\n  - **Docker** (recommended) — easiest “zero-to-hero” setup\n  - **Node.js 18+** ([download](https://nodejs.org/)) — needed for the `npx` setup\n- **CamoFox Browser Server** must be running (it is **not** a downloadable desktop binary — use Docker, `npx`, or build from source)\n- **An MCP-compatible client**: VS Code (Copilot), Cursor, Claude Desktop, or any MCP client\n\n## Quick Start\n\nPick ONE option below.\n\n### Option A: Docker (Recommended — Easiest)\n\n**1) Start CamoFox Browser**\n\n```bash\ndocker run -d -p 9377:9377 --name camofox-browser ghcr.io/redf0x1/camofox-browser:latest\n```\n\n**2) Verify it’s running**\n\n```bash\ncurl http://localhost:9377/health\n```\n\n**3) Add MCP config to your editor** (see configs below)\n\n**4) Paste the verification prompt into your AI agent** (see below)\n\n### Option B: npx (Quick — Needs Node.js 18+)\n\n**1) Start CamoFox Browser (keep this terminal open)**\n\n```bash\nnpx camofox-browser@latest\n```\n\n**2) In another terminal, verify:**\n\n```bash\ncurl http://localhost:9377/health\n```\n\n**3) Add MCP config to your editor** (see configs below)\n\n**4) Paste the verification prompt into your AI agent**\n\n### Option C: From Source (Developers)\n\n**1) Clone and start CamoFox Browser**\n\n```bash\ngit clone https://github.com/redf0x1/camofox-browser.git\ncd camofox-browser \u0026\u0026 npm install \u0026\u0026 npm run build \u0026\u0026 npm start\n```\n\n**2) Clone and build CamoFox MCP**\n\n```bash\ngit clone https://github.com/redf0x1/camofox-mcp.git\ncd camofox-mcp \u0026\u0026 npm install \u0026\u0026 npm run build\n```\n\n**3) Add MCP config** (see configs below — use `node` path instead of `npx`)\n\n**4) Paste the verification prompt**\n\n### MCP Client Configuration\n\n#### VS Code (Copilot)\n\n- File: `.vscode/mcp.json` (in your workspace root)\n- Create the file if it doesn't exist\n\n```json\n{\n  \"servers\": {\n    \"camofox\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"camofox-mcp@latest\"],\n      \"env\": {\n        \"CAMOFOX_URL\": \"http://localhost:9377\"\n      }\n    }\n  }\n}\n```\n\n#### Claude Desktop\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- Linux: `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"camofox\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"camofox-mcp@latest\"],\n      \"env\": {\n        \"CAMOFOX_URL\": \"http://localhost:9377\"\n      }\n    }\n  }\n}\n```\n\nNote: Claude Desktop uses `\"mcpServers\"` not `\"servers\"`.\n\n#### Cursor\n\n- File: `~/.cursor/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"camofox\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"camofox-mcp@latest\"],\n      \"env\": {\n        \"CAMOFOX_URL\": \"http://localhost:9377\"\n      }\n    }\n  }\n}\n```\n\n#### From Source (use `node` instead of `npx`)\n\n```json\n{\n  \"servers\": {\n    \"camofox\": {\n      \"type\": \"stdio\",\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/camofox-mcp/dist/index.js\"],\n      \"env\": {\n        \"CAMOFOX_URL\": \"http://localhost:9377\"\n      }\n    }\n  }\n}\n```\n\nNote: This example is for VS Code. For Claude Desktop or Cursor, use `\"mcpServers\"` instead of `\"servers\"`.\n\n### 3. Verify Setup\n\n\u003e After configuring your MCP client, restart your editor. Then paste this prompt into your AI agent:\n\n```text\nVerify my CamoFox MCP setup. Run these checks and report results:\n\n1) Call `server_status` — is the browser server connected?\n2) If connected: `create_tab` with url `https://example.com`\n3) `navigate_and_snapshot` on that tab (wait for text: \"Example Domain\")\n4) `list_profiles` to confirm profile storage is accessible\n5) `close_tab` for the test tab\n\nIf any step fails, diagnose the issue and suggest a fix.\nReport: ✅ pass or ❌ fail for each step, plus overall status.\n```\n\n\u003e **Prerequisites:** You must configure your MCP client first (Step 2 above). The AI agent can do everything else.\n\n**Manual verification (optional):**\n\n```bash\ncurl http://localhost:9377/health\n# Expected: {\"ok\":true,\"browserConnected\":true}\n```\n\n### Docker\n\n#### Quick Start with Docker\n\n```bash\n# Standalone (connect to an existing CamoFox browser server running on the host)\ndocker run -i --rm -e CAMOFOX_URL=http://host.docker.internal:9377 ghcr.io/redf0x1/camofox-mcp:latest\n\n# Browser only (recommended): starts the CamoFox browser server in the background\ndocker compose up -d\n\n# MCP (stdio): start the browser with compose, then launch the MCP container on-demand\n# Option A: plain docker (attach stdin; uses the compose network)\ndocker run -i --rm --network=camofox-mcp_default -e CAMOFOX_URL=http://camofox-browser:9377 ghcr.io/redf0x1/camofox-mcp:latest\n\n# Option B: compose run (no TTY; attaches stdin/stdout for JSON-RPC)\ndocker compose run --rm -T camofox-mcp\n```\n\nNote: `docker compose up -d` detaches and does not provide stdin, so it can only be used to run the browser service.\nYour MCP client should launch the MCP container separately (using `docker run -i ...` or `docker compose run -T ...`).\n\n#### VS Code MCP Configuration (Docker)\n\n```json\n{\n  \"servers\": {\n    \"camofox\": {\n      \"type\": \"stdio\",\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"-i\", \"--rm\", \"-e\", \"CAMOFOX_URL=http://host.docker.internal:9377\", \"ghcr.io/redf0x1/camofox-mcp:latest\"]\n    }\n  }\n}\n```\n\n#### Claude Desktop Configuration (Docker)\n\n```json\n{\n  \"mcpServers\": {\n    \"camofox\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"-i\", \"--rm\", \"-e\", \"CAMOFOX_URL=http://host.docker.internal:9377\", \"ghcr.io/redf0x1/camofox-mcp:latest\"],\n      \"type\": \"stdio\"\n    }\n  }\n}\n```\n\nIMPORTANT: Do NOT use `-t` flag — TTY corrupts the JSON-RPC stdio stream.\n\n## Tools (35)\n\n### Tab Management\n| Tool | Description |\n|------|-------------|\n| `create_tab` | Create a new tab with anti-detection fingerprinting |\n| `close_tab` | Close a tab and release resources |\n| `list_tabs` | List all open tabs with URLs and titles |\n\n### Presets\n| Tool | Description |\n|------|-------------|\n| `list_presets` | List all available geo presets supported by the connected CamoFox browser server |\n\n### Geo Presets\n\n`create_tab` supports optional regional configuration via a named `preset`, plus per-field overrides:\n\n- `preset` — preset name (e.g., `japan`, `vietnam`, `uk`)\n- `locale` — BCP-47 locale (e.g., `ja-JP`)\n- `timezoneId` — IANA timezone (e.g., `Asia/Tokyo`)\n- `geolocation` — `{ latitude, longitude }`\n- `viewport` — `{ width, height }`\n\nResolution order: `preset` defaults → individual field overrides → server defaults.\n\nBuilt-in presets (when supported by your camofox-browser server):\n\n| Preset | Locale | Timezone | Location |\n|--------|--------|----------|----------|\n| `us-east` | en-US | America/New_York | New York |\n| `us-west` | en-US | America/Los_Angeles | Los Angeles |\n| `japan` | ja-JP | Asia/Tokyo | Tokyo |\n| `uk` | en-GB | Europe/London | London |\n| `germany` | de-DE | Europe/Berlin | Berlin |\n| `vietnam` | vi-VN | Asia/Ho_Chi_Minh | Ho Chi Minh City |\n| `singapore` | en-SG | Asia/Singapore | Singapore |\n| `australia` | en-AU | Australia/Sydney | Sydney |\n\nExample:\n\n```json\n{\n  \"userId\": \"agent1\",\n  \"url\": \"https://example.com\",\n  \"preset\": \"japan\",\n  \"viewport\": { \"width\": 1920, \"height\": 1080 }\n}\n```\n\nTip: call `list_presets` to discover what presets the connected server supports (including any custom preset file configured server-side).\n\n### Navigation\n| Tool | Description |\n|------|-------------|\n| `navigate` | Navigate to a URL, waits for page load |\n| `go_back` | Browser back button |\n| `go_forward` | Browser forward button |\n| `refresh` | Reload current page |\n\n### Interaction\n| Tool | Description |\n|------|-------------|\n| `click` | Click element by ref (from snapshot) or CSS selector |\n| `type_text` | Type text into input fields by ref or CSS selector |\n| `camofox_press_key` | Press keyboard keys (Enter, Tab, Escape, etc.) |\n| `scroll` | Scroll page up or down by pixel amount |\n| `camofox_scroll_element` | Scroll inside a container element (modal, sidebar, scrollable div) |\n| `camofox_hover` | Hover over an element to trigger tooltips, dropdowns, or hover states |\n| `camofox_wait_for` | Wait for page readiness after navigation or dynamic updates |\n| `camofox_evaluate_js` | Execute JavaScript in page context (may require API key) |\n\n### Batch / Composite\n| Tool | Description |\n|------|-------------|\n| `fill_form` | Fill multiple form fields in one call, with optional submit click |\n| `type_and_submit` | Type into a field and press a key (default: Enter) |\n| `navigate_and_snapshot` | Navigate to a URL, wait for readiness, and return a snapshot |\n| `scroll_and_snapshot` | Scroll then capture a fresh snapshot |\n| `camofox_scroll_element_and_snapshot` | Scroll inside a container element, then take a snapshot |\n| `batch_click` | Click multiple elements sequentially with per-click results |\n\n### Observation\n| Tool | Description |\n|------|-------------|\n| `snapshot` | Get accessibility tree — PRIMARY way to read pages. Token-efficient |\n| `screenshot` | Take visual screenshot as base64 PNG |\n| `get_links` | Get all hyperlinks with URLs and text |\n| `camofox_wait_for_text` | Wait for specific text to appear on the page |\n\n### Search\n| Tool | Description |\n|------|-------------|\n| `web_search` | Search via 14 engines: Google, YouTube, Amazon, Bing, DuckDuckGo, Reddit, GitHub, StackOverflow, Wikipedia, Twitter, LinkedIn, Facebook, Instagram, TikTok |\n\n### Session\n| Tool | Description |\n|------|-------------|\n| `import_cookies` | Import cookies for authenticated sessions |\n| `get_stats` | Get session statistics and performance metrics |\n| `camofox_close_session` | Close all browser tabs for a user session |\n\n### Session Profiles\n| Tool | Description |\n|------|-------------|\n| `save_profile` | Save cookies from an active tab to a named on-disk profile |\n| `load_profile` | Load a saved profile's cookies into an active tab (restores login sessions) |\n| `list_profiles` | List saved profiles with metadata (cookie count, save date, description) |\n| `delete_profile` | Delete a saved profile from disk |\n\n### Health\n| Tool | Description |\n|------|-------------|\n| `server_status` | Check CamoFox server health and connection |\n\n## Session Profiles\n\nSession Profiles let you persist authenticated browser state across MCP restarts by saving/loading cookies to/from disk.\n\n### Tools\n\n- `save_profile` — export cookies from an active tab and save them under a profile name\n- `load_profile` — load a saved profile into an active tab (imports cookies)\n- `list_profiles` — list all saved profiles and metadata\n- `delete_profile` — delete a saved profile permanently\n\n### Configuration\n\n- `CAMOFOX_PROFILES_DIR` — directory used to store profiles (default: `~/.camofox-mcp/profiles/`)\n- `CAMOFOX_AUTO_SAVE` — enable auto-save/auto-load of an \"auto profile\" (default: `true`). Set to `false` to disable.\n\n### Auto-save / auto-load\n\nBy default, CamoFox MCP will persist sessions automatically:\n\n- On `close_tab` and `camofox_close_session`, cookies are exported and saved to `_auto_{userId}` (best-effort; 5-second timeout).\n- On `create_tab`, if `_auto_{userId}` exists, it is loaded automatically (best-effort; 5-second timeout).\n\nNote: auto-load imports cookies, which may require `CAMOFOX_API_KEY` if the CamoFox browser server enforces authentication. For local setups, auto-load works without a key.\n\n### Example flow\n\n1. `create_tab`\n2. Navigate + login interactively\n3. `save_profile` (from the logged-in tab)\n4. Restart your MCP client/server\n5. `create_tab`\n6. `load_profile`\n7. `navigate` — you should already be authenticated\n\n### Docker persistence\n\nMount a volume so profiles survive container restarts:\n\n```bash\ndocker run -i --rm \\\n  -e CAMOFOX_URL=http://host.docker.internal:9377 \\\n  -v \"$HOME/.camofox-mcp/profiles:/root/.camofox-mcp/profiles\" \\\n  ghcr.io/redf0x1/camofox-mcp:latest\n```\n\n## API Key Setup\n\nThe API key is **optional**. All 35 tools work without a key when the CamoFox browser server doesn't enforce authentication (the default for local setups).\n\nIf your CamoFox browser server **has authentication enabled**, these tools need a matching key:\n\n- `import_cookies`\n- `camofox_evaluate_js`\n- `load_profile` (imports cookies)\n- Auto-save / auto-load session profiles (imports cookies on `create_tab`)\n\nWithout a matching key, these tools return a clear \"API key required\" error with setup instructions.\n\n### How it works\n\nThe key is a **shared secret** between **both** servers and must match exactly:\n\n```\nAI Agent -\u003e (MCP tool call) -\u003e CamoFox MCP (sends CAMOFOX_API_KEY) -\u003e (HTTP) -\u003e CamoFox Browser Server (validates key)\n```\n\n### Set the key on both servers\n\n**1) Start CamoFox Browser Server with a key** (exact flags may vary by camofox-browser version):\n\n```bash\nexport CAMOFOX_API_KEY=\"your_shared_secret\"\n./camofox-browser\n```\n\nOr (if supported by your camofox-browser build):\n\n```bash\n./camofox-browser --api-key \"your_shared_secret\"\n```\n\n**2) Configure your MCP client to pass the same key**:\n\n```json\n{\n  \"servers\": {\n    \"camofox\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"camofox-mcp@latest\"],\n      \"env\": {\n        \"CAMOFOX_URL\": \"http://localhost:9377\",\n        \"CAMOFOX_API_KEY\": \"your_shared_secret\"\n      }\n    }\n  }\n}\n```\n\nNote: This example is for VS Code. For Claude Desktop or Cursor, use `\"mcpServers\"` instead of `\"servers\"`.\n\n### What happens without an API key?\n\n**All tools work** when the CamoFox browser server doesn't require authentication (default for local/Docker setups).\n\nIf the browser server **does** enforce auth and no key is set, cookie import, profile load, and JS evaluation return a clear error: \"CamoFox server requires authentication. Set CAMOFOX_API_KEY environment variable.\"\n\n⚠️ **Key mismatch** between MCP and browser server → affected tools return **\"Forbidden\"**. Ensure the **same** key is set on both servers.\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CAMOFOX_URL` | `http://localhost:9377` | CamoFox server URL |\n| `CAMOFOX_TIMEOUT` | `30000` | Request timeout in ms |\n| `CAMOFOX_API_KEY` | — | Shared secret for authenticated operations. Only needed if the CamoFox browser server enforces auth |\n| `CAMOFOX_PROFILES_DIR` | `~/.camofox-mcp/profiles` | Directory to store persistent session profiles |\n| `CAMOFOX_AUTO_SAVE` | `true` | Auto-save on close + auto-load on create via `_auto_{userId}` |\n| `CAMOFOX_DEFAULT_USER_ID` | `default` | Default userId for new tabs when none specified |\n| `CAMOFOX_TAB_TTL_MS` | `1800000` | Tab TTL in milliseconds (30min). Set to 0 to disable auto-eviction |\n| `CAMOFOX_MAX_TABS` | `100` | Maximum tracked tabs |\n| `CAMOFOX_VISITED_URLS_LIMIT` | `50` | Max URLs to keep in tab history |\n| `CAMOFOX_SWEEP_INTERVAL_MS` | `60000` | Sweep interval in milliseconds (1min) |\n\n## Architecture\n\n```\nAI Agent (Claude, GPT, etc.)\n       │\n       │ MCP Protocol (stdio)\n       ▼\n┌─────────────────┐\n│  CamoFox MCP    │  ← This package\n│  (TypeScript)   │\n└────────┬────────┘\n         │\n         │ REST API (HTTP)\n         ▼\n┌─────────────────┐\n│  CamoFox Server │  ← Anti-detection browser\n│  (Port 9377)    │\n└────────┬────────┘\n         │\n         │ Browser Engine\n         ▼\n┌─────────────────┐\n│  Camoufox       │  ← Firefox-based, fingerprint spoofing\n│  (Firefox)      │\n└─────────────────┘\n```\n\n## How It Works\n\n1. **Your AI agent** sends MCP tool calls (e.g., `create_tab`, `navigate`, `snapshot`)\n2. **CamoFox MCP** translates these into REST API calls to the CamoFox server\n3. **CamoFox server** manages a Camoufox browser with anti-detection features\n4. **Each tab** gets a unique fingerprint — different user agent, screen size, WebGL, fonts, etc.\n5. **Websites see** what appears to be a normal human browser, not automation\n\n## Anti-Detection Features\n\nCamoFox (via [Camoufox](https://github.com/daijro/camoufox)) provides:\n\n- ✅ Unique browser fingerprint per tab\n- ✅ Human-like user agent rotation\n- ✅ WebGL fingerprint spoofing\n- ✅ Canvas fingerprint protection\n- ✅ Screen resolution randomization\n- ✅ Font enumeration protection\n- ✅ Navigator properties masking\n- ✅ Timezone/locale consistency\n\n## Related Projects\n\n| Project | Description |\n|---------|-------------|\n| [CamoFox Browser Server](https://github.com/redf0x1/camofox-browser) | Anti-detection browser server (required) |\n| [Camoufox](https://github.com/daijro/camoufox) | Firefox fork with C++ fingerprint spoofing |\n\n## Troubleshooting\n\n**Quick troubleshoot (paste into your AI agent):**\n\n```text\nSomething isn't working with my CamoFox setup. Please diagnose:\n\n1) Call `server_status` — check browser server connection\n2) If connected, try `create_tab` and navigate to any URL\n3) If that works, try `import_cookies` with a simple test cookie\n4) Report what's working and what's failing\n5) Suggest specific fixes for any issues found\n```\n\n- **Connection refused** (curl fails / `server_status` fails) -\u003e CamoFox Browser Server is not running or `CAMOFOX_URL` is wrong. Verify with:\n  ```bash\n  curl http://localhost:9377/health\n  ```\n- **\"Forbidden\" on `import_cookies` / profile load / `camofox_evaluate_js`** -\u003e API key mismatch. Ensure the **same** `CAMOFOX_API_KEY` is set on both servers.\n- **\"API key required\"** -\u003e The CamoFox browser server requires authentication. Set `CAMOFOX_API_KEY` on both servers (see API Key Setup).\n- **Session profiles not auto-restoring** -\u003e Auto-load imports cookies, which requires `CAMOFOX_API_KEY` if the browser server enforces auth. Also confirm `CAMOFOX_AUTO_SAVE` is not set to `false`.\n- **Not sure if setup is working?** -\u003e Run the health check above, then ask your agent to call `server_status`, then try the Quick Start smoke test.\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a PR.\n\n## Security\n\n### URL Navigation (SSRF Awareness)\n\nCamoFox MCP forwards URLs to the CamoFox Browser Server for navigation. This is core functionality — the browser visits whatever URL you provide.\n\n**In trusted environments** (local development, single-user): No special precautions needed.\n\n**In shared/cloud environments**: Be aware that the browser can access any URL reachable from its host, including internal network services. Consider:\n\n- Running the browser server in an isolated network (Docker network, VPC)\n- Using firewall rules to restrict outbound access from the browser container\n- Not exposing the MCP server to untrusted clients\n\n### API Key\n\nWhen `CAMOFOX_API_KEY` is set, all sensitive operations (cookie import/export, JavaScript evaluation) require authentication. Always set an API key in production environments.\n\n### Profile Storage\n\nSession profiles are stored locally at `~/.camofox-mcp/profiles/` with restricted file permissions (`0o600`). Profiles contain cookies which may include authentication tokens — treat them as sensitive data.\n\n## License\n\n[MIT](LICENSE)\n\n## Acknowledgments\n\n- [CamoFox Browser Server](https://github.com/redf0x1/camofox-browser) — The anti-detection browser server this MCP wraps\n- [Camoufox](https://github.com/daijro/camoufox) — Firefox fork with C++ fingerprint spoofing\n- [Model Context Protocol](https://modelcontextprotocol.io/) — The protocol standard by Anthropic\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredf0x1%2Fcamofox-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredf0x1%2Fcamofox-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredf0x1%2Fcamofox-mcp/lists"}