# camofox-mcp

MCP server for [CamoFox](https://github.com/jo-inc/camofox-browser) — anti-detect browser automation for AI agents.

**No local browser is launched.** This is a thin MCP wrapper over the CamoFox REST API running elsewhere (Docker, remote server, etc.).

## Why

CamoFox provides anti-detect browsing via [Camoufox](https://camoufox.com) (Firefox fork with C++ fingerprint spoofing). This MCP server lets any MCP-compatible AI agent (OpenClaw, Claude Desktop, etc.) use it as a tool.

## Quick Start

### 1. Start CamoFox server somewhere

```bash
# Docker (recommended)
docker run -p 9377:9377 jo-inc/camofox-browser

# Or standalone
git clone https://github.com/jo-inc/camofox-browser
cd camofox-browser && npm install && npm start
```

### 2. Run the MCP server

```bash
# With uvx (no install needed)
CAMOFOX_URL=http://your-server:9377 uvx camofox-mcp

# Or install and run
pip install camofox-mcp
CAMOFOX_URL=http://your-server:9377 camofox-mcp
```

### 3. Configure your MCP client

#### OpenClaw (mcporter)

```bash
mcporter config add camofox --stdio \
  "CAMOFOX_URL=http://your-server:9377 CAMOFOX_USER=agent uvx camofox-mcp"
```

#### Claude Desktop / Cursor

```json
{
  "mcpServers": {
    "camofox": {
      "command": "uvx",
      "args": ["camofox-mcp"],
      "env": {
        "CAMOFOX_URL": "http://your-server:9377",
        "CAMOFOX_USER": "agent"
      }
    }
  }
}
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `CAMOFOX_URL` | `http://localhost:9377` | CamoFox server URL |
| `CAMOFOX_USER` | `default` | User ID for session isolation |
| `CAMOFOX_TIMEOUT` | `30` | HTTP request timeout (seconds) |

## Tools

| Tool | Description |
|------|-------------|
| `camofox_health` | Check server status |
| `camofox_navigate` | Open URL → get accessibility snapshot |
| `camofox_snapshot` | Get current page snapshot |
| `camofox_click` | Click element by ref (e1, e2…) |
| `camofox_type` | Type text into element |
| `camofox_press` | Press keyboard key |
| `camofox_scroll` | Scroll page (up/down/left/right) |
| `camofox_navigate_tab` | Navigate existing tab to new URL |
| `camofox_search` | Use search macro (@google_search, etc.) |
| `camofox_links` | Extract all links from page |
| `camofox_screenshot` | Take screenshot (returns file path) |
| `camofox_tabs` | List open tabs |
| `camofox_close` | Close a tab |
| `camofox_close_all` | Close all tabs |
| `camofox_back` | Browser history back |
| `camofox_forward` | Browser history forward |

### Search Macros

`@google_search` · `@youtube_search` · `@amazon_search` · `@reddit_search` · `@wikipedia_search` · `@twitter_search` · `@yelp_search` · `@spotify_search` · `@netflix_search` · `@linkedin_search` · `@instagram_search` · `@tiktok_search` · `@twitch_search`

## Architecture

```
AI Agent ←(MCP/stdio)→ camofox-mcp ←(REST/HTTP)→ CamoFox Server ←→ Camoufox Browser
```

The MCP server is stateless — all state lives in the CamoFox server. Multiple MCP clients can connect to the same CamoFox instance with different `CAMOFOX_USER` values for session isolation.

## Security

- All user inputs (URLs, text, refs) are JSON-encoded — no shell interpolation
- Tab IDs are URL-encoded before use in paths
- No credentials are stored or transmitted beyond what CamoFox requires
- The MCP server never launches a browser — it only proxies to an existing CamoFox instance

## License

MIT