Skip to main content
Glama
camoufox-mcp-python

camoufox-mcp-python

by zc-libre

camoufox-mcp-python

中文文档

Python License: MIT PyPI

A Model Context Protocol (MCP) server that provides browser automation tools powered by Camoufox — a stealthy, anti-detect browser built on Firefox. It exposes a Playwright-MCP compatible tool interface using accessibility snapshots and ref-based element targeting.

Think of it as playwright-mcp, but with built-in anti-detection and fingerprint spoofing.

Features

  • Anti-detect browser fingerprinting — Camoufox automatically spoofs browser fingerprints to bypass bot detection

  • Ref-based accessibility snapshots — Interact with page elements via accessibility refs, no CSS selectors needed

  • Human-like cursor movement — Cursor humanization enabled by default for realistic interactions

  • WebRTC leak protection — WebRTC blocked by default to prevent IP leaks

  • Isolated browser profiles by default — Each server process gets a fresh temporary profile that is deleted on close; pass --user-data-dir to reuse a persistent profile

  • GeoIP auto-matching — Automatically match browser locale/timezone to proxy location

  • Proxy support — Full proxy support including authentication

  • WebGL fingerprint control — Specify WebGL vendor/renderer pair or block entirely

  • Custom addons — Load custom Firefox addons or exclude defaults like uBlock Origin

  • Advanced fingerprint config — Override any BrowserForge fingerprint property or use a custom fingerprint

  • Firefox preferences — Set custom Firefox user preferences

  • Browser caching — Optional page/request caching for performance

  • Privacy controls — Block WebGL and image loading to reduce leaks and bandwidth

  • Multi-tab management — Create, close, select, and list browser tabs

  • Modal & dialog handling — Handle JavaScript dialogs and file choosers

  • Console & network monitoring — Inspect console messages and network requests

Related MCP server: Camoufox MCP

Quick Start

Use with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

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

Use with Claude Code

claude mcp add camoufox -- uvx camoufox-mcp-python

Use with VS Code / Cursor

Add to .vscode/mcp.json:

{
  "servers": {
    "camoufox": {
      "command": "uvx",
      "args": ["camoufox-mcp-python"]
    }
  }
}

Use with Codex CLI

Add to codex.json or pass via CLI:

codex --mcp-server "npx @anthropic-ai/mcp-proxy -- uvx camoufox-mcp-python"

Pin a specific version

{
  "mcpServers": {
    "camoufox": {
      "command": "uvx",
      "args": ["--from", "camoufox-mcp-python==0.2.1", "camoufox-mcp-python"]
    }
  }
}

CLI Options

Option

Description

--headless / --no-headless

Run the browser headlessly (default: on)

--proxy <url>

Proxy server URL (supports user:pass@host:port)

--os <os>

Target OS fingerprint: windows, macos, linux (repeatable)

--humanize [seconds]

Cursor humanization (default: on). Pass a number for max duration, or false to disable

--geoip [ip]

Auto-match locale/timezone to proxy IP, or specify a target IP

--locale <locale>

Browser locale(s), e.g. en-US (repeatable, comma-separated)

--window <WxH>

Outer window size, e.g. 1280x720

--block-webrtc / --no-block-webrtc

Block WebRTC to prevent IP leaks (default: on)

--block-webgl

Disable WebGL

--block-images

Block image requests to reduce bandwidth

--disable-coop

Disable COOP for cross-origin iframe interactions

--user-data-dir <path>

Optional persistent profile directory. If omitted, each server process uses an isolated temporary profile that is deleted on close

--caps <groups>

Enable capability groups, e.g. dangerous (enables browser_evaluate)

--webgl-config <v,r>

WebGL vendor/renderer pair, e.g. "Intel Inc.,Intel(R) UHD Graphics 620"

--addons <paths>

Paths to extracted Firefox addons (repeatable, comma-separated)

--exclude-addons <names>

Default addons to exclude, e.g. UBO (repeatable, comma-separated)

--config <json>

Camoufox fingerprint properties as a JSON string

--enable-cache

Cache previous pages and requests (uses more memory)

--firefox-user-prefs <json>

Firefox user preferences as a JSON string

--i-know-what-im-doing

Silence Camoufox warnings for advanced configurations

--debug

Print the config being sent to Camoufox

Examples

# Zero-config anti-detection (headless + humanize + block-webrtc on by default)
camoufox-mcp-python

# With proxy and GeoIP matching
camoufox-mcp-python --proxy http://user:pass@proxy.example.com:8080 --geoip

# Visible browser for debugging
camoufox-mcp-python --no-headless --debug

# Custom WebGL fingerprint
camoufox-mcp-python --webgl-config "Intel Inc.,Intel(R) UHD Graphics 620" --os windows

# Custom fingerprint properties
camoufox-mcp-python --config '{"navigator.hardwareConcurrency": 8}'

# With caching and custom Firefox prefs
camoufox-mcp-python --enable-cache --firefox-user-prefs '{"dom.webnotifications.enabled": false}'

# Privacy-hardened mode
camoufox-mcp-python --block-webgl --block-images

# Disable default anti-detection for debugging
camoufox-mcp-python --no-headless --humanize false --no-block-webrtc --debug

# Enable JavaScript evaluation
camoufox-mcp-python --caps dangerous

Available Tools

Navigation

Tool

Description

browser_navigate

Navigate to a URL

browser_navigate_back

Go back to the previous page

Snapshot & Interaction

Tool

Description

browser_snapshot

Capture an accessibility snapshot of the current page

browser_click

Click an element by ref (supports double-click, right-click, modifiers)

browser_hover

Hover over an element

browser_drag

Drag from one element to another

browser_select_option

Select option(s) in a dropdown

Input

Tool

Description

browser_type

Type text into an editable element (supports slow typing and submit)

browser_press_key

Press a keyboard key or key combination

browser_fill_form

Fill multiple form fields in a single call

Page

Tool

Description

browser_take_screenshot

Take a screenshot (viewport, full page, or element)

browser_console_messages

Retrieve collected console messages

browser_network_requests

List network requests seen by the page

browser_resize

Resize the viewport

browser_wait_for

Wait for text to appear/disappear, or a fixed duration

browser_close

Close the browser session

Tabs

Tool

Description

browser_tabs

List, create, close, or select browser tabs

Modals & Files

Tool

Description

browser_handle_dialog

Accept or dismiss a JavaScript dialog

browser_file_upload

Handle a file chooser and upload files

Dangerous (requires --caps dangerous)

Tool

Description

browser_evaluate

Execute arbitrary JavaScript on the page or an element

How It Works

The server uses Camoufox (a Firefox-based anti-detect browser) through Playwright's async API. Pages are represented as accessibility snapshots in YAML format, where each interactive element is assigned a ref identifier. The AI model reads the snapshot, identifies the target ref, and calls the appropriate tool — no fragile CSS/XPath selectors required.

AI Model  ←→  MCP Server  ←→  Camoufox Browser
                  │
                  ├── Accessibility Snapshot (YAML)
                  ├── Ref-based element targeting
                  └── Anti-detect fingerprinting

Local Development

# Clone and install
git clone https://github.com/user/camoufox-mcp.git
cd camoufox-mcp
uv pip install --python .venv/bin/python -e .

# Run the server
./.venv/bin/camoufox-mcp-python --headless

# Or run as a module
./.venv/bin/python -m camoufox_mcp --headless

# Smoke test
./.venv/bin/python -m compileall camoufox_mcp
./.venv/bin/camoufox-mcp-python --help

Requirements

Note: The first launch on a new machine may trigger automatic Camoufox binary and addon downloads.

License

MIT

Available Tools

19 tools
browser_clickC

Perform click on a web page.

Inputs: ref (required), button, element, modifiers, +1 more.

browser_closeA

Close the current browser session.

Inputs: no named parameters.

browser_console_messagesC

Return collected console messages.

Inputs: level, filename.

browser_dragD

Drag from one ref to another.

Inputs: endRef (required), startRef (required), endElement (required), startElement (required).

browser_file_uploadD

Handle an active file chooser.

Inputs: paths.

browser_fill_formB

Fill multiple form fields in one call.

Inputs: fields (required).

browser_handle_dialogC

Accept or dismiss an active dialog.

Inputs: accept (required), promptText.

browser_hoverC

Hover over a web page element.

Inputs: ref (required), element.

browser_navigateC

Navigate to a URL.

Inputs: url (required).

browser_navigate_backA

Go back to the previous page.

Inputs: no named parameters.

browser_network_requestsB

List network requests seen by the page.

Inputs: filename, includeStatic.

browser_press_keyC

Press a key on the keyboard.

Inputs: key (required).

browser_resizeB

Resize the current page viewport.

Inputs: width (required), height (required).

browser_select_optionC

Select one or more values in a dropdown.

Inputs: ref (required), values (required), element.

browser_snapshotC

Capture the current accessibility snapshot.

Inputs: filename.

browser_tabsC

List, create, close, or select a browser tab.

Inputs: action (required), index.

browser_take_screenshotB

Take a screenshot of the viewport, full page, or a referenced element.

Inputs: ref, type, element, filename, +1 more.

browser_typeC

Type text into an editable element.

Inputs: ref (required), text (required), slowly, submit, +1 more.

browser_wait_forB

Wait for text to appear or disappear, or for a fixed duration.

Inputs: text, time, textGone.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 19 tools

    Disambiguation5/5

    Each tool targets a distinct interaction or observation (e.g., click vs. hover vs. drag, type vs. press_key vs. fill_form). The only mild overlap is between type and fill_form, but their descriptions clearly scope them to single-element vs. multi-field actions. Overall, no two tools are easily confused.

    Naming Consistency4/5

    All tools share the 'browser_' prefix, creating a strong family resemblance. However, the suffix pattern is mixed: some are verb-first (browser_click, browser_navigate) while others are resource-first (browser_tabs, browser_console_messages, browser_network_requests). Despite this, the prefix and clear action descriptions make the naming predictable.

    Tool Count4/5

    At 19 tools, the set is slightly above the typical 3-15 range but well-justified for a comprehensive browser automation server. The count covers navigation, input, observation, and tab/window management without feeling redundant. A few tools could theoretically be combined (e.g., screenshot modes), but the granularity is reasonable.

    Completeness5/5

    The tool surface covers the core browser automation lifecycle: navigation (navigate, back), interaction (click, hover, drag, select, type, press_key, fill_form), waiting (wait_for), and introspection (snapshot, console, network, screenshot). It also handles dialogs, file uploads, tabs, resize, and closing, leaving no obvious dead ends for standard automation scenarios. Advanced features like JS evaluation are absent but not essential for basic browser control.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      Not graded
      maintenance
      A MCP server that provides browser automation tools, allowing users to navigate websites, take screenshots, click elements, fill forms, and execute JavaScript through Playwright.
      8
      2
      Apache 2.0
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server for anti-detection browser automation that uses Camoufox to bypass bot detection and spoof digital fingerprints. It enables AI agents to perform human-like web interactions, including realistic cursor movements, humanized click delays, and automatic cookie popup dismissal.
      36
      110 npm
      7
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for controlling a local camofox-browser instance, enabling LLM agents to perform web automation tasks such as navigation, interaction, snapshotting, and content extraction.
      92 npm
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Browser automation MCP server using Camoufox anti-detect browser with fingerprint spoofing, geolocation/timezone spoofing, and human-like cursor movement.
      14
      1
      Apache 2.0