# Camoufox MCP

Camoufox MCP is a local stdio MCP server for authorized browser automation. Use it only on sites and systems that you own or are permitted to test. It does not grant permission to bypass site policies, access controls, or legal restrictions.

The server embeds one Camoufox browser session, manages multiple tabs, and exposes 21 browser tools to MCP clients. Debian/Linux is the primary supported runtime target. Linux and Docker use Xvfb-backed virtual headful mode by default.

## Pinned versions

- Python package: `cloverlabs-camoufox==0.6.0`
- Default installed build selector: `150.0.2-alpha.26`
- Default release provenance: release tag `v150.0.2-beta.25`

Release tags are provenance labels only. Python and Docker installations use the same manifest-pinned default build. `CAMOUFOX_MCP_BROWSER_VERSION` accepts only selectors listed in `browser_builds.json`. Startup verifies the selected local build; it never downloads a browser, changes the selection, reads Camoufox's global active version, or silently falls back.

## Install with Python

Python 3.12, `uv`, and a Debian/Linux runtime are required.

```sh
uv sync --frozen
uv run python -m playwright install-deps firefox
uv run python -m camoufox sync
uv run camoufox-mcp-install-browser
uv run camoufox-mcp
```

`camoufox-mcp-install-browser` reads `browser_builds.json`, downloads the pinned build, selects it, and validates the executable, runtime library, and version metadata. In a non-TTY environment it suppresses repetitive addon percentage output while preserving error diagnostics. `playwright install-deps firefox` installs system libraries only. Do not run `playwright install firefox`; Camoufox uses its own browser builds. Xvfb is required for the default `virtual` display mode on Linux. The Python startup preflight is supported on Linux and checks the selected build in the XDG Camoufox cache (`$XDG_CACHE_HOME`, or `~/.cache` when unset). The default preflight is not supported on non-Linux platforms.

## Install with Docker

The image supports Linux amd64 only and contains the manifest-pinned browser build. Docker Desktop users must start the Docker daemon and select Linux containers before building or running it.

```sh
docker build --platform linux/amd64 -t camoufox-mcp:dev .
docker run --rm -i camoufox-mcp:dev
```

Use `-i` for MCP stdio and do not allocate a TTY with `-t`. The image runs as UID 10001 under `tini`. Browser files are stored in `/home/camoufox/.cache/camoufox` and are installed at image build time. Runtime startup performs local installation checks only.

## MCP client configuration

Python checkout:

```json
{
  "mcpServers": {
    "camoufox": {
      "command": "uv",
      "args": ["run", "python", "-m", "camoufox_mcp"]
    }
  }
}
```

Docker:

```json
{
  "mcpServers": {
    "camoufox": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "camoufox-mcp:dev"]
    }
  }
}
```

All protocol data uses stdout. Diagnostics and logs use stderr only.

### Hermes

Hermes 应直接启动虚拟环境生成的 `camoufox-mcp` 可执行文件，不需要传递 `args`。这样可以避开 Hermes 对重复 `--args` 和列表配置的解析限制：

```sh
hermes mcp add camoufox --command "/absolute/path/to/.venv/bin/camoufox-mcp"
```

对应的 YAML 配置无需 `args` 字段：

```yaml
mcp_servers:
  camoufox:
    command: /absolute/path/to/.venv/bin/camoufox-mcp
```

当前清单默认选择 `150.0.2-alpha.26`，因此无需额外设置 `CAMOUFOX_MCP_BROWSER_VERSION`。只有在清单未来重新加入其他已验证构建时，才需要用该环境变量显式切换。

## Tools

Lifecycle:

- `browser_start`: Start the managed browser and return its status.
- `browser_status`: Return state, build selector, display mode, active page, and page count.
- `browser_stop`: Close all pages and release browser and display resources.

Tabs:

- `page_new`: Create a tab and optionally navigate it to a URL.
- `page_list`: List registered pages and active-page metadata.
- `page_select`: Select a registered page as active.
- `page_close`: Close a specified page or the active page.

Navigation:

- `page_navigate`: Navigate to an allowed URL.
- `page_back`: Navigate backward in history.
- `page_forward`: Navigate forward in history.
- `page_reload`: Reload a page.

Observation:

- `page_snapshot`: Return a bounded semantic snapshot.
- `page_screenshot`: Return a bounded PNG image and page metadata.

Interaction:

- `page_click`: Click one uniquely resolved target.
- `page_fill`: Replace the value of one uniquely resolved target.
- `page_type`: Type text sequentially with an optional delay.
- `page_press`: Press a key on one uniquely resolved target.
- `page_hover`: Hover over one uniquely resolved target.
- `page_select_option`: Select an option by value.
- `page_wait`: Wait on a discriminated `condition`: `sleep` for 1 through 10000 milliseconds, `load_state` for `load`, `domcontentloaded`, or `networkidle`, or `target` for `attached`, `detached`, `visible`, or `hidden`. Sleep waits do not accept `timeout_ms`. Other waits default to the configured action timeout, capped at 60000 milliseconds; an explicit `timeout_ms` must be between 1 and 60000. The wait holds the selected page's operation lock for its full duration.
- `page_evaluate`: Evaluate arbitrary JavaScript in the selected page context with JSON-compatible input. Expressions default to a 100000-character limit, encoded arguments to 1000000 bytes, and results and evaluation error messages to `CAMOUFOX_MCP_MAX_EVALUATE_BYTES`. JavaScript can read storage available to the page and make requests permitted by the browser, so this tool assumes a trusted, authorized MCP client. Error-message length limiting is a resource boundary, not secret removal.

## Target JSON

Role and accessible name are preferred:

```json
{
  "target": {
    "kind": "role",
    "value": "button",
    "name": "Sign in",
    "exact": true
  }
}
```

Supported `kind` values are `role`, `label`, `placeholder`, `text`, `test_id`, `css`, and `xpath`. The optional zero-based `index` selects an explicit match. Without `index`, zero matches return `TARGET_NOT_FOUND` and multiple matches return `TARGET_NOT_UNIQUE`.

## Environment variables

- `CAMOUFOX_MCP_BROWSER_VERSION`: Browser build selector. Default `150.0.2-alpha.26`; only selectors in `browser_builds.json` are accepted.
- `CAMOUFOX_MCP_DISPLAY_MODE`: `virtual`, `headful`, or `headless`. Default `virtual`.
- `CAMOUFOX_MCP_ACTION_TIMEOUT_MS`: Action timeout, 1 to 300000. Default `30000`.
- `CAMOUFOX_MCP_NAVIGATION_TIMEOUT_MS`: Navigation timeout, 1 to 300000. Default `30000`.
- `CAMOUFOX_MCP_MAX_SNAPSHOT_CHARS`: Snapshot limit, 1 to 200000. Default `50000`.
- `CAMOUFOX_MCP_MAX_EVALUATE_EXPRESSION_CHARS`: Evaluation expression limit, 1 to 1000000 characters. Default `100000`.
- `CAMOUFOX_MCP_MAX_EVALUATE_ARGUMENT_BYTES`: Encoded evaluation argument limit, 1 to 5000000 bytes. Default `1000000`.
- `CAMOUFOX_MCP_MAX_EVALUATE_BYTES`: Encoded evaluation result and error-message limit, 2 to 5000000 bytes. Default `1000000`.
- `CAMOUFOX_MCP_MAX_SCREENSHOT_BYTES`: Screenshot limit, 1 to 50000000. Default `10000000`.
- `CAMOUFOX_MCP_LOG_LEVEL`: Python log level. Default `INFO`.

Configuration is loaded once at process startup. Invalid values fail startup instead of silently falling back or reading Camoufox's global active version.

## Tests

```sh
uv run python -m pytest tests/unit tests/contract -q
uv run ruff check src tests
docker build --platform linux/amd64 -t camoufox-mcp:dev .
uv run python -m pytest tests/integration/test_docker_smoke.py -m integration -q
```

The integration test serves a deterministic local page, drives the container through the official MCP stdio client, and verifies the pinned browser build. It skips with an explicit reason when the Docker daemon is unavailable.

## Initial release limitations

- One browser session per MCP server process.
- No persistent profile, cookies, or login state.
- No HTTP or SSE transport.
- No proxy pool, file upload, or download management.
- No automated CAPTCHA handling.
- Only `http`, `https`, and `about:blank` navigation is allowed.
- No automatic browser upgrades or fallback after startup failure.
- No guarantee of bypassing anti-bot systems or site risk controls.