camoufox-mcp

🦊 Camoufox MCP

Anti-detection browser automation for AI agents

MCP server for browser automation using Camoufox - an anti-detection Firefox browser.

Installation

npx camoufox-mcp

Claude Desktop Configuration

Add to claude_desktop_config.json:

Basic:

{
  "mcpServers": {
    "camoufox": {
      "command": "npx",
      "args": ["camoufox-mcp"]
    }
  }
}

With Proxy (via env vars):

{
  "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:

{
  "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:

• create_session with contextPath: "github-cookies.json" — returns a sessionId
• new_page with url: "https://github.com" and the sessionId — opens GitHub already logged in

Run two accounts simultaneously:

• create_session with contextPath: "account1.json" — session A
• create_session with contextPath: "account2.json" — session B
• new_page in session A — logged in as account 1
• new_page in session B — logged in as account 2

Save session state for later:

• Log in manually in a session
• save_session with outputPath: "my-session.json" — exports cookies + localStorage
• Next time, create_session with contextPath: "my-session.json" — restored

Context File Format

Context files use Playwright's storageState format:

{
  "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:

{
  "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:

{
  "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:

{ "proxy": { "enabled": true, "server": "http://1.2.3.4:8080" } }

SOCKS5 Proxy:

{ "proxy": { "enabled": true, "server": "socks5://1.2.3.4:1080" } }

With Authentication (using env vars):

{
  "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 - The anti-detection Firefox browser
• camoufox-js - JavaScript/TypeScript bindings

License

MIT