# Camoufox Browser CLI CLI-first browser automation powered by [Camoufox](https://github.com/CloverLabsAI/camoufox), with optional MCP support. Host support for `camoufox-browser`: Linux and macOS only. The project supports three user-facing workflows: - `camoufox-browser`: the primary CLI for humans and agents - `camoufox-mcp`: an optional MCP server that wraps the same command layer - `skills/camoufox/SKILL.md`: a repo skill installed through `npx skills` ## Features - Shared browser operation layer for CLI and MCP - Persistent browser session through a lightweight background daemon - Accessibility snapshot refs for agent-friendly interaction - Anti-detection launch via Camoufox - Tabs, screenshots, console/network inspection, uploads, dialogs, and form automation ## Installation ### CLI only ```bash pip install camoufox-browser # or pipx install camoufox-browser # or uv tool install camoufox-browser ``` ### CLI + MCP ```bash pip install "camoufox-browser[mcp]" # or uv tool install "camoufox-browser[mcp]" ``` ### From source ```bash git clone https://github.com/rlgrpe/camoufox-browser-cli.git cd camoufox-browser-cli uv sync uv run camoufox-browser --help ``` ### Install browser binary After installing the package, download the Camoufox browser binary: ```bash camoufox-browser install # or directly: python -m camoufox fetch uvx camoufox fetch ``` #### Linux system dependencies ```bash # Ubuntu/Debian sudo apt install -y libgtk-3-0 libx11-xcb1 libasound2 # Arch sudo pacman -S gtk3 libx11 libxcb cairo libasound alsa-lib ``` ## CLI Usage The primary UX is similar to `agent-browser`: call the CLI directly and let it start its background daemon automatically when needed. ```bash camoufox-browser open https://example.com camoufox-browser snapshot camoufox-browser click 'button:Sign in' camoufox-browser fill 'textbox:Email' me@example.com --submit camoufox-browser screenshot --output page.png camoufox-browser close ``` Run `camoufox-browser --help` for the full command surface. ### Core commands | Command | Description | |---------|-------------| | `camoufox-browser open ` | Navigate to URL | | `camoufox-browser snapshot` | Print accessibility tree with refs | | `camoufox-browser click ` | Click an element | | `camoufox-browser fill ` | Fill or type into an element | | `camoufox-browser select [more-values...]` | Select dropdown value(s) | | `camoufox-browser upload [more-files...]` | Upload file(s) to a file input | | `camoufox-browser drag

` | Drag and drop | | `camoufox-browser press ` | Press keyboard key | | `camoufox-browser screenshot [--output FILE] [--full-page] [--ref REF]` | Take screenshot | | `camoufox-browser eval ''` | Run JavaScript on page | | `camoufox-browser wait [--text TEXT] [--text-gone TEXT] [--time N]` | Wait for condition | | `camoufox-browser close` | Close browser (daemon stays running) | ### Session and inspection | Command | Description | |---------|-------------| | `camoufox-browser console [--level error\|warning\|info\|debug]` | Browser console output | | `camoufox-browser network [--all]` | Recorded network requests | | `camoufox-browser resize ` | Resize viewport | | `camoufox-browser tabs list\|new\|close [index]\|select ` | Manage tabs | | `camoufox-browser dialog accept\|dismiss [prompt_text]` | Handle pending dialog | | `camoufox-browser fill-form ''` | Fill multiple fields from JSON | ### Advanced daemon control These commands are optional. The normal workflow does not require them. | Command | Description | |---------|-------------| | `camoufox-browser start [--headless] [--os windows\|macos\|linux] [--proxy PROXY]` | Start daemon explicitly | | `camoufox-browser stop` | Stop daemon | | `camoufox-browser status` | Check if daemon is running | ### Element refs `camoufox-browser snapshot` prints an accessibility tree. Interactive elements include a `[ref=...]` label: ```text button "Sign in" [ref=button:Sign in] textbox "Email" [ref=textbox:Email] link "Forgot password?" [ref=link:Forgot password?] ``` Pass the ref value to interaction commands: ```bash camoufox-browser click 'button:Sign in' camoufox-browser fill 'textbox:Email' me@example.com ``` ## MCP Server Install the optional MCP extra: ```bash pip install "camoufox-browser[mcp]" ``` The MCP server is a thin wrapper over the same operation layer used by `camoufox-browser`. ### Add to Claude Code ```bash claude mcp add camoufox-mcp -- uvx --from "camoufox-browser[mcp]" camoufox-mcp ``` ### Claude Desktop configuration ```json { "mcpServers": { "camoufox-mcp": { "command": "uvx", "args": ["--from", "camoufox-browser[mcp]", "camoufox-mcp"] } } } ``` ### From source ```json { "mcpServers": { "camoufox-mcp": { "command": "uv", "args": [ "run", "--extra", "mcp", "--directory", "/path/to/camoufox-browser-cli", "camoufox-mcp" ] } } } ``` ## Skill Usage The skill does not introduce a separate runtime. It teaches the agent to use `camoufox-browser`, and it should be installed through `npx skills`. ```bash npx skills add https://github.com/rlgrpe/camoufox-browser-cli --skill camoufox ``` Project-local install for specific agents: ```bash npx skills add https://github.com/rlgrpe/camoufox-browser-cli --skill camoufox -a claude-code -a codex ``` ## Development ```bash uv sync uv run python -m unittest uv run python -m compileall camoufox_mcp uv build --wheel ``` ## Related Projects - [Camoufox](https://github.com/CloverLabsAI/camoufox) - [MCP](https://modelcontextprotocol.io/) - [FastMCP](https://github.com/jlowin/fastmcp) - [agent-browser](https://github.com/vercel-labs/agent-browser)