<div align="center">
# 🦊 Camoufox MCP
**Anti-detection browser automation for AI agents**
[](https://npmjs.org/package/camoufox-mcp)
[](https://npmjs.org/package/camoufox-mcp)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
MCP server for browser automation using [Camoufox](https://camoufox.com/) - an anti-detection Firefox browser.
</div>
## 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
