Content
# 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 <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:
```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)
