io.github.baixianger/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?

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.

Page Management

Navigation & Interaction

Inspection

Context Injection

Monitoring

Utility

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:

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