camoufox-reverse-mcp: an MCP server for reading obfuscated JavaScript in a real browser

What the project is

The project is an MCP server, a Model Context Protocol server, built on an anti-fingerprinting browser and designed for JavaScript reverse engineering. The repository description calls it an anti-detection browser MCP server with 35 JavaScript reverse engineering tools and a C++ engine layer for JSVMP fingerprint tracking.

The idea is worth stating plainly, because it is unusual. Most AI coding assistants can write code but cannot see what a web page actually does. This server hands the assistant a browser that is already instrumented, and exposes the instrumentation as callable tools. So the assistant can ask for the list of scripts on a page, search them for a keyword, hook a function and read the trace, capture the network traffic, and read the accessibility tree, all without writing a line of Playwright.

The README is explicit about the client set, naming Claude Code, Cursor and Cline among others, and the tool count in the title is 35.

The primary language is Python, the licence is not a standard identifier, the default branch is main, and the recent releases are v1.8.0 from 2026-09-08, v1.7.0 from the same day and v1.6.0 from 2026-09-07. The last push was on 2026-09-08 with the project not archived, and the repository publishes no GitHub releases.

The top-level listing is a normal Python project: src/, tests/, docs/, a pyproject.toml, and both a Chinese and an English README. The docs/ directory carries the per-version release notes and a couple of validation write-ups, which is the shape of a project that treats its own release process as documentation.

The dependency list is short for what the tool does:

git clone https://github.com/WhiteNightShadow/camoufox-reverse-mcp.git
cd camoufox-reverse-mcp
pip install -e .

So the MCP Python SDK at 1.29 or newer but below 2, camoufox with the geoip extra at 0.4.0 or newer below 0.6, playwright at 1.40.0 or newer, and esprima at 4.0.1 or newer, which is a JavaScript parser. The build backend is hatchling and the package lives at src/camoufox_reverse_mcp, with the console script named camoufox-reverse-mcp.

The capability table, and the honesty in it

The README has a table comparing what Camoufox gives you against its limits, and it is the most useful part of the document for anyone deciding whether the tool fits.

The browser is Firefox, through Camoufox. Runtime analysis covers explicit world, Frame, hook and network capture. JSVMP investigation is described as runtime probes and source instrumentation, verified against specific targets. And persistent hooks are described as Context initialisation with explicit pending and teardown boundaries.

The second half of that table is where the care is. The core advantages are listed as five points, and every one of them has a caveat attached.

Camoufox modifies fingerprint information at the C++ layer and does not rely on page JavaScript patches, which avoids the common descriptor and prototype leaks. But Juggler isolation reduces some page-side automation traces, while hooks, environment differences and timing may still be observed.

BrowserForge generates fingerprints according to real-world traffic statistics distributions rather than assembling them at random, which is a real improvement on random values. But the tool is usable for anti-crawler and environment-dependency analysis, and the availability for a specific site must be verified with actual samples.

And hooks can optionally use Object.defineProperty protection against being overwritten, but a locked property may require rebuilding the Context to recover.

That last one is the kind of limitation a research tool should state and most do not. If you hook a property and the page protects it by redefining the descriptor, your hook can be removed, and the recovery path is to rebuild the whole Context rather than re-patching. The README says so.

The overall posture is a tool for understanding how a site decides that it is being automated, not a promise that it will not be detected. The difference between those two claims is the difference between a research instrument and a marketing one, and it is worth noticing that the README keeps them apart.

The tool surface, grouped by what you are trying to find out

The tool list is the substance of the project, and it is grouped into seven families.

Browser control is the foundation. launch_browser starts Camoufox and can select an installed version once with browser_version without changing the active configuration. close_browser releases the resources. navigate goes to a URL, with pre_inject_hooks and redirect_chain tracing. reload and take_screenshot, which supports full page and a specific element, and take_snapshot, which returns the accessibility tree and is described as token efficient. Then click, type_text, wait_for to wait for an element or a URL match, and get_page_info for the current URL, title, viewport size and Frame list.

Script analysis is next, with scripts(action) handling list, get and save, and search_code searching by keyword across the whole page when script_url is None or a single script when it is given, with automatic detection of compressed files and character-level context.

Hooking and tracing is the category the project is really about. hook_function hooks or traces a function, across the main world, a Frame, with persistence, and with waiting for a dynamic target. get_trace_data reads or clears the function trace, filtered by world and Frame. inject_hook_preset injects a preset in one call, with xhr, fetch, crypto, websocket, debugger_bypass, cookie and runtime_probe among the presets. remove_hooks removes all hooks and restores the original objects. And get_console_logs returns the page's console output.

Network analysis is the fourth family. network_capture(action) controls start, stop, clear and status. list_network_requests lists what was captured with filters for URL, domain, method, type and status code. get_network_request fetches the full detail with max_body_size controlling body truncation. get_request_initiator returns the JavaScript call stack that made the request. And intercept_request can log, block, modify, mock or stop a request.

That last one is a request-interception tool, and it is the capability that makes the project useful for studying a site's own validation logic rather than only reading it.

The remaining families are cookies and storage, with cookies(action) for get, set and delete, get_storage for localStorage and sessionStorage, and export_state and import_state for the whole browser state. Then verification and environment: verify_signer_offline, which takes a list of samples and compares character by character to locate the first divergence point, and check_environment, a one-stop self-check of the MCP, the dependencies, the Camoufox Python, active and installed versions and the customised build state. And reset_browser_state, which clears leftover hooks, capture, routes and engine trace without closing the browser.

JSVMP analysis, and the mapping between anti-bot type and tool path

The JSVMP section is the most technically specific part of the README, and it starts with a mapping table because the right tool depends on the kind of protection in front of you.

The table separates three anti-crawler types. For signature-based protection, where the environment is the signature, with RS 5 and 6 and AK sensor_data as representatives, the recommended path is instrumentation(action="install") and the disabled paths are pre_inject_hooks and hook_jsvmp_interpreter(mode="proxy"). For behaviour-based protection, where the parameters are the signature, with TK JSVMP and JY gt4 as representatives, the recommended path is hook_jsvmp_interpreter(mode="proxy"). And for pure obfuscation, with common JavaScript obfuscation tools as representatives, any combination is allowed.

That table is a genuinely useful piece of engineering documentation, because the failure mode of a tool like this is applying the wrong technique: hooking the interpreter when the signature is environmental wastes effort and can trip the protections you are trying to study.

The three JSVMP tools are then described. hook_jsvmp_interpreter is a runtime probe with mode="proxy" for full coverage and mode="transparent" for signature safety. instrumentation(action) is source-level instrumentation with install to register the rewrite, log to get the log, stop, reload and status. And compare_env collects browser environment fingerprints so they can be compared against Node.js and jsdom.

Then there is a set of precise limits, and they read like the notes of somebody who got them wrong first. Setting include_source_site=True at install time adds a stable site_id and a monotonic seq, and the log returns a source_sites sidecar mapping back to the original character ranges of the intercepted script. The capability is off by default, and it represents the source position of the obfuscated JavaScript and will not guess the VM's program counter, the opcode or the pre-protection source position.

For scripts over 200KB that need full rewriting, on_oversized="force" has to be set explicitly, and otherwise the recommendation is to use property filtering and turn off rewrite_calls as needed to control the overhead.

The engine-level tracing is a separate feature, and it is the one with the strictest requirement. trace_property_access needs the customised camoufox-reverse build, and returns an error hint if it is not installed, without affecting the other tools. The reverse.5 build declares 77 trace points and older compatible builds declare 75, and it does not rewrite page JavaScript objects, descriptors or prototypes. It supports capture, start, stop, query, clear and status actions, with summary, timeline, sequence and search views, get, set and call operations, and filtering by object and native site. The collect_values option only takes a safe snapshot after tracing and lists what it skipped, so it does not represent the values at the moment the event happened.

Each enable_trace=True launch uses an independent run directory and only controls that browser's PID, so it does not clean up or switch off other MCP instances. The trace files can be listed across independent run directories for after-the-fact analysis with list_trace_files, and queried from the trace cache with query_trace_file.

Installing it, and the client configuration

There are two installation routes, and the first one is unusual enough to be worth reading.

The recommended route is to paste a request into your AI coding tool's chat box:

the request names the project and its GitHub address, and the assistant does the rest.

The idea is that the assistant does the clone, installs the dependencies and writes the MCP server configuration for you. That is a real convenience for the target audience, since the whole point of the tool is that the user is already talking to an assistant, and it removes the manual step of knowing where a client keeps its MCP configuration.

It is also the route that deserves a second thought. The instructions being pasted ask an agent to clone a repository, install its dependencies and register it as a server that can control a browser, and an agent that follows that prompt without reading the code first will do it. The manual route below gives you the same outcome with the clone step under your own eyes.

The manual route is three commands:

{
  "mcpServers": {
    "camoufox-reverse": {
      "command": "python",
      "args": ["-m", "camoufox_reverse_mcp"]
    }
  }
}

And the note under it says that v1.1.0 pinned the MCP Python SDK to a compatible v1 series and normalises the optional parameter schema, so it works with strict services such as Moonshot and Kimi that require every tool parameter to include a type.

Then the client configuration, one block per client. For Cursor, in .cursor/mcp.json:

{
  "mcpServers": {
    "camoufox-reverse": {
      "command": "python",
      "args": ["-m", "camoufox_reverse_mcp", "--headless"]
    }
  }
}

For Claude Code:

{
  "mcpServers": {
    "camoufox-reverse": {
      "command": "python",
      "args": [
        "-m", "camoufox_reverse_mcp",
        "--proxy", "http://127.0.0.1:7890",
        "--geoip",
        "--humanize"
      ]
    }
  }
}

json { "mcpServers": { "camoufox-reverse": { "command": "python", "args": ["-m", "camoufox_reverse_mcp", "--headless"] } } }

[project]
name = "camoufox-reverse-mcp"
version = "1.8.0"
description = "Anti-detection browser MCP server for JavaScript reverse engineering"
requires-python = ">=3.10"
license = {text = "MIT"}
dependencies = [
    "mcp>=1.29,<2",
    "camoufox[geoip]>=0.4.0,<0.6",
    "playwright>=1.40.0",
    "esprima>=4.0.1",
]

json { "mcpServers": { "camoufox-reverse": { "command": "python", "args": [ "-m", "camoufox_reverse_mcp", "--proxy", "http://127.0.0.1:7890", "--geoip", "--humanize" ] } } } ``` The differences between the three blocks are the interesting part. Cursor's runs the module with no extra arguments. Claude Code's adds --headless. The proxied version adds --proxy with a local address, --geoip and --humanize. So the same server supports headed and headless operation, a proxy for outbound traffic, geolocation spoofing and randomised interaction timing, and the flags are the whole configuration surface.

The MCP server is started as python -m camoufox_reverse_mcp in all three, so the module is directly runnable, and there is also a console script named camoufox-reverse-mcp declared in the package metadata.

How to evaluate it, and what to check first

There are four things to consider, and the first is about how you will use it.

This is a research instrument, and the README frames it as one. The JSVMP section is written by somebody who has been defeated by a real target and written down what worked and what did not, with the mapping table distinguishing protection types and the recommended path for each. If you are analysing a site you own, are authorised to analyse, or are studying the behaviour of anti-bot systems in general, this is a substantial body of tooling. If you are looking for something to get past a specific site's protections reliably, the README itself says availability for a specific site must be verified with actual samples, and that is an admission that the outcome is site-dependent.

Second, the customised browser requirement for the engine-level tracing. trace_property_access needs the camoufox-reverse build, and without it that tool returns an error while the rest keep working. The rest of the project works with the stock Camoufox, and the two can coexist from Camoufox Python 0.5 onwards without changing the persistent active version. The constraint on the version string is specific: browser_version must use repo/version or an exact directory, and if several assets share a version you must pass the exact directory. The chosen version must have the same full version and build as the active browser, to avoid mixing versions of shared upstream resources. The MCP does not download browsers, does not modify config.json and does not trigger a cache migration.

Third, the evidence discipline in the newer releases, which is the part that makes the tool usable for real conclusions. The v1.6.0 notes describe correlation of concurrent responses to the same URL by Request object, full collection of cookies and Set-Cookie headers, and explicit states for failure, eviction, unfinished tasks and truncation. The v1.7.0 notes describe three rounds across nine independent tasks where failures were kept and fed back into corrections, ending with signature, WASM and pagination all passing independent acceptance. And v1.8.0 describes real work against a KProtect VM, javascript-obfuscator control flow flattening and CryptoJS and FingerprintJS locally, with failures going into the fix and re-verification loop.

A project that reports its failures alongside its wins is rare, and the v1.6.0 note about the offline signer verification not passing samples without a valid expected value is a good example: the default browser path is unchanged, and a sample with no valid expected value no longer passes by accident.

Fourth, the operational surface. reset_browser_state clears hooks, capture, routes and the current engine trace without closing the browser, and the environment self-check reports the MCP, the dependencies, the Camoufox versions and the customised build status in one call, which matters for a tool that runs a browser and keeps state around. And check_environment is the first thing to run when something is misbehaving.

What you get is a well-documented research harness with a large tool surface, a careful account of its own limits, and a version history that reads like an engineer's notebook. The cost is that it needs a real browser, a customised build for one of its features, and enough patience to read the per-version release notes, which are where the actual methodological detail lives.

Editorial conclusion

Adopt camoufox-reverse-mcp if you are analysing how a site detects automation, whether that is your own site, one you are authorised to test, or a general study of anti-bot systems, because the tool surface is wide and the README is candid about where each technique stops working. Do not treat it as a guarantee that a particular site will be reached, since the documentation itself says availability must be verified with actual samples, and do not paste the install request into an agent without reading what it asks the agent to do, because it clones a repository, installs its dependencies and registers a server that can control a browser. Before you commit, read the per-version release notes in docs, since the methodological detail lives there rather than in the overview, run check_environment first when something misbehaves, and note that the engine-level property tracing needs the separate camoufox-reverse browser build while the rest of the tooling works with stock Camoufox.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. WhiteNightShadow/camoufox-reverse-mcp on GitHub