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.

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.

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:

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

Docker:

{
  "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 和列表配置的解析限制：

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

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

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:

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

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.