Camoufox Browser CLI

CLI-first browser automation powered by 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

pip install camoufox-browser
# or
pipx install camoufox-browser
# or
uv tool install camoufox-browser

CLI + MCP

pip install "camoufox-browser[mcp]"
# or
uv tool install "camoufox-browser[mcp]"

From source

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:

camoufox-browser install
# or directly:
python -m camoufox fetch
uvx camoufox fetch

Linux system dependencies

# 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.

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 <url>	Navigate to URL
camoufox-browser snapshot	Print accessibility tree with refs
camoufox-browser click <ref>	Click an element
camoufox-browser fill <ref> <text>	Fill or type into an element
camoufox-browser select <ref> <value> [more-values...]	Select dropdown value(s)
camoufox-browser upload <ref> <file> [more-files...]	Upload file(s) to a file input
camoufox-browser drag <start-ref> <end-ref>	Drag and drop
camoufox-browser press <key>	Press keyboard key
camoufox-browser screenshot [--output FILE] [--full-page] [--ref REF]	Take screenshot
camoufox-browser eval '<js>'	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 <width> <height>	Resize viewport
camoufox-browser tabs list|new|close [index]|select <index>	Manage tabs
camoufox-browser dialog accept|dismiss [prompt_text]	Handle pending dialog
camoufox-browser fill-form '<json-array>'	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:

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:

camoufox-browser click 'button:Sign in'
camoufox-browser fill 'textbox:Email' me@example.com

MCP Server

Install the optional MCP extra:

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

claude mcp add camoufox-mcp -- uvx --from "camoufox-browser[mcp]" camoufox-mcp

Claude Desktop configuration

{
  "mcpServers": {
    "camoufox-mcp": {
      "command": "uvx",
      "args": ["--from", "camoufox-browser[mcp]", "camoufox-mcp"]
    }
  }
}

From source

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

npx skills add https://github.com/rlgrpe/camoufox-browser-cli --skill camoufox

Project-local install for specific agents:

npx skills add https://github.com/rlgrpe/camoufox-browser-cli --skill camoufox -a claude-code -a codex

Development

uv sync
uv run python -m unittest
uv run python -m compileall camoufox_mcp
uv build --wheel

Related Projects

• Camoufox
• MCP
• FastMCP
• agent-browser