Content
# Tool List
[中文](README.md) | [English](README_en.md)
> MCP Server for Camoufox, designed for JavaScript reverse engineering.
An MCP (Model Context Protocol) server that enables AI coding assistants (Claude Code, Cursor, Cline, etc.) to perform reverse engineering operations on target websites through the **Camoufox** anti-fingerprinting browser, including:
* Interface parameter analysis
* Static analysis of JS files
* Dynamic breakpoint debugging
* Function Hook tracking
* Network traffic interception
* JSVMP bytecode analysis
* Cookie/storage management
## Why Choose Camoufox?
| Feature | chrome-devtools-mcp | **camoufox-reverse-mcp** |
|-----|--------------------|-----------------------|
| Browser Engine | Chrome (Puppeteer) | **Firefox (Camoufox)** |
| Anti-Detection Solution | None | **C++ engine-level fingerprint forgery** |
| Debugging Capability | Limited (no breakpoints) | **Playwright + JS Hook** |
| JSVMP Analysis | None | **Interpreter instrumentation + source code-level rewriting** |
| Hook Persistence | Not supported | **Context-level persistence, automatic re-injection after navigation** |
**Core Advantages:**
- Camoufox modifies fingerprint information at the **C++ level**, making it undetectable from the JavaScript layer.
- Juggler protocol sandbox isolation makes Playwright **completely undetectable by page JavaScript**.
- BrowserForge generates fingerprints based on **real-world traffic statistics distribution**, not random combinations.
- Works normally on various strong anti-scraping websites like RS, AK, JY, CF, etc.
- Hooks use `Object.defineProperty` with **anti-overwrite protection**, preventing page scripts from recovering original methods.
## Getting Started
### Method 1: Direct Installation via AI Chatbox (Recommended)
Enter the following in your AI coding tool's (Cursor / Claude Code / Codex, etc.) chatbox:
```
Help me install this MCP tool: camoufox-reverse-mcp
Project address: https://github.com/WhiteNightShadow/camoufox-reverse-mcp
```
The AI will complete the cloning, dependency installation, and MCP Server configuration.
### Method 2: Manual Installation
```bash
git clone https://github.com/WhiteNightShadow/camoufox-reverse-mcp.git
cd camoufox-reverse-mcp
pip install -e .
```
### Client Configuration
<details>
<summary><b>Cursor (.cursor/mcp.json)</b></summary>
```json
{
"mcpServers": {
"camoufox-reverse": {
"command": "python",
"args": ["-m", "camoufox_reverse_mcp"]
}
}
}
```
</details>
<details>
<summary><b>Claude Code</b></summary>
```json
{
"mcpServers": {
"camoufox-reverse": {
"command": "python",
"args": ["-m", "camoufox_reverse_mcp", "--headless"]
}
}
}
```
</details>
<details>
<summary><b>Claude Code (with Proxy)</b></summary>
```json
{
"mcpServers": {
"camoufox-reverse": {
"command": "python",
"args": [
"-m", "camoufox_reverse_mcp",
"--proxy", "http://127.0.0.1:7890",
"--geoip",
"--humanize"
]
}
}
}
```
</details>
## Available Tools (35)
### Browser Control
| Tool | Description |
|------|------|
| `launch_browser` | Launch Camoufox anti-fingerprinting browser |
| `close_browser` | Close browser, release resources |
| `navigate` | Navigate to specified URL (supports pre_inject_hooks, redirect_chain tracking) |
| `reload` | Refresh page |
| `take_screenshot` | Take screenshot (supports full page, specified element) |
| `take_snapshot` | Get page accessibility tree (token efficient) |
| `click` / `type_text` | Click element / input text |
| `wait_for` | Wait for element appearance or URL match |
| `get_page_info` | Get current page URL, title, viewport size |
### JS Execution and Debugging
| Tool | Description |
|------|------|
| `evaluate_js` | Execute arbitrary JS expression in page context (multi-strategy JSON parsing) |
### Script Analysis
| Tool | Description |
|------|------|
| `scripts(action)` | Script management: `list` list / `get` get source code / `save` save to local |
| `search_code` | Search keywords ( `script_url=None` full search, specify URL then single script search, automatically detect compression file with character-level context) |
### Hook and Tracking
| Tool | Description |
|------|------|
| `hook_function` | Hook or track function: `mode="intercept"` inject code / `mode="trace"` non-invasive tracking |
| `inject_hook_preset` | One-click inject preset Hook (xhr / fetch / crypto / websocket / debugger_bypass / cookie / runtime_probe) |
| `remove_hooks` | Remove all hooks and restore original object |
| `get_console_logs` | Get page console output |
### Network Analysis
| Tool | Description |
|------|------|
| `network_capture(action)` | Network capture control: `start` / `stop` / `clear` / `status` |
| `list_network_requests` | List captured requests (supports URL / domain / method / type / status code filtering) |
| `get_network_request` | Get complete request details ( `max_body_size` controls body truncation) |
| `get_request_initiator` | Get JS call stack that initiated the request |
| `intercept_request` | Intercept request: log / block / modify / mock / stop |
### JSVMP Reverse Analysis
> **Anti-scraping type → tool path对照表**
>
> | Anti-scraping type | Representative | ✅ Recommended path | ❌ Disabled |
> |---|---|---|---|
> | **Signature type** (environment is signature) | RS 5/6, AK sensor_data | `instrumentation(action="install")` | `pre_inject_hooks`, `hook_jsvmp_interpreter(mode="proxy")` |
> | **Behavior type** (parameter signature) | TK JSVMP, JY gt4 | `hook_jsvmp_interpreter(mode="proxy")` | — |
> | **Pure obfuscation** | Common JS obfuscation tools | Arbitrary combination | — |
| Tool | Description |
|------|------|
| `hook_jsvmp_interpreter` | JSVMP runtime probe ( `mode="proxy"` full coverage / `mode="transparent"` signature security) |
| `instrumentation(action)` | Source code-level instrumentation: `install` register rewriting / `log` get log / `stop` stop / `reload` reload / `status` view status |
| `compare_env` | Browser environment fingerprint collection, used for comparison with Node.js/jsdom |
### Cookie and Storage
| Tool | Description |
|------|------|
| `cookies(action)` | Cookie management: `get` / `set` / `delete` |
| `get_storage` | Get localStorage / sessionStorage |
| `export_state` / `import_state` | Export / import complete browser state |
### Verification and Environment
| Tool | Description |
|------|------|
| `verify_signer_offline` | Offline verify signature function: input sample list, character-level comparison, locate first deviation point |
| `check_environment` | One-stop self-check: MCP version, dependencies, browser state, camoufox-reverse customized browser detection |
| `reset_browser_state` | Clean up residuals (hooks / capture / routes), do not close browser |
### Engine-level Property Tracking (added in v1.1.0)
> Requires [camoufox-reverse customized browser](https://github.com/WhiteNightShadow/camoufox-reverse/releases). Returns error prompt if not installed, does not affect other tool usage.
| Tool | Description |
|------|------|
| `trace_property_access` | C++ engine-level DOM property access tracking (JSVMP undetectable). Supports summary/timeline/sequence/search four views. `duration=0` reads all events since launch, `duration>0` opens a new tracking window. `collect_values=True` automatically reads all property values from browser (large values saved to file) |
| `list_trace_files` | List all local trace files (for post-analysis) |
| `query_trace_file` | Query specified historical trace file, supports filtering by object/keyword |
## Usage Scenarios
### Scenario 1: Reverse Login Interface Signature Parameters
```
1. launch_browser()
2. inject_hook_preset("xhr")
3. inject_hook_preset("crypto")
4. navigate("https://example.com/login")
5. type_text("#username", "test") → click("#login-btn")
6. list_network_requests(method="POST")
7. get_request_initiator(request_id=3) ← Locate signature function
8. search_code("sign") ← Search signature code
9. hook_function("window.getSign", mode="trace")
10. reload() → get_console_logs() ← Collect tracking data
```
### Scenario 2: General JSVMP Reverse (RS / AK / Self-developed VMP)
```
1. launch_browser()
2. network_capture(action="start")
3. navigate("https://target-site.com/")
4. list_network_requests(resource_type="script") ← Find VMP script
5. instrumentation(action="install", url_pattern="**/vmp_target*.js", mode="ast")
6. inject_hook_preset("cookie", persistent=True)
7. instrumentation(action="reload") ← Make instrumentation take effect
8. instrumentation(action="log", type_filter="tap_get") ← See what VMP reads
9. instrumentation(action="log", type_filter="tap_method") ← See what VMP calls
10. compare_env() ← Collect environment for Node.js completion
```
### Scenario 3: Verify Protocol Code
```
1. launch_browser() → navigate("https://target.com")
2. network_capture(action="start")
3. # Trigger target operation, collect signed request
4. reqs = list_network_requests(url_filter="api/search")
5. # Extract samples
6. verify_signer_offline(
signer_code="(s) => ({'X-Bogus': mySign(s.url)})",
samples=[{"id": "r1", "input": {...}, "expected": {"X-Bogus": "..."}}]
)
```
> 👉 Complete anti-scraping type identification and workflow see [docs/JSVMP_PLAYBOOK.md](docs/JSVMP_PLAYBOOK.md)
### Scenario 4: Engine-level Tracking JSVMP Environment Fingerprint (added in v1.1.0)
> Requires [camoufox-reverse customized browser](https://github.com/WhiteNightShadow/camoufox-reverse/releases)
```
1. launch_browser(enable_trace=True) ← Launch browser with C++ tracking
2. navigate("https://www.douyin.com/video/xxx") ← JSVMP execution, events automatically recorded
3. trace_property_access(duration=0, mode="summary", collect_values=True)
→ Returns JSVMP actual read 42 DOM properties, access frequency, and real values
→ Small values inline returned, large values (Canvas/WebGL/Cookie, etc.) automatically saved to
~/.cache/camoufox-reverse/values/ directory
# View attribute access rhythm by timeline
4. trace_property_access(duration=0, mode="timeline", bucket_ms=500)
# Filter by object
5. trace_property_access(duration=0, filter_object="webgl")
# Search specific attribute
6. trace_property_access(duration=0, mode="search", search_query="cookie")
```
**Difference from compare_env**:
- `trace_property_access`: Track JSVMP **actual read** attributes (accurate, C++ level, undetectable)
- `compare_env`: Collect browser **all** environment attributes (full, JS level)
- Path B environment disguise, use trace results to decide "which attributes to supplement", avoid supplementing too many and introducing new leakage points
## Technical Architecture
```
┌─────────────────────────────────────────────────┐
│ AI Coding Assistant (Cursor / Claude) │
│ ↕ MCP (stdio) │
├─────────────────────────────────────────────────┤
│ camoufox-reverse-mcp (35 tools) │
│ ┌──────────┬──────────┬──────────┬──────────┐ │
│ │Navigation│ Script │Debugging │ Hooking │ │
│ │ │ Analysis │ │ │ │
│ ├──────────┼──────────┼──────────┼──────────┤ │
│ │ Network │ JSVMP │ Cookie │ Verify │ │
│ │ Capture │ Analysis │ Storage │ Signer │ │
│ ├──────────┴──────────┴──────────┴──────────┤ │
│ │ ★ PropertyTracer (trace_property_access) │ │
│ │ C++ engine-level DOM property tracking (JSVMP undetectable) │ │
│ └───────────────────────────────────────────┘ │
│ ↕ Playwright API │
├─────────────────────────────────────────────────┤
│ Camoufox (anti-fingerprinting Firefox, Juggler protocol) │
│ C++ engine-level fingerprint forgery · BrowserForge real fingerprint distribution │
└─────────────────────────────────────────────────┘
```
## Update Records
### v1.1.0 (2026-04-22) — Engine-level Property Tracking
> Added 3 tools, `launch_browser` added `enable_trace` parameter.
**Added tools**
- `trace_property_access` — C++ engine-level DOM property access tracking (JSVMP undetectable), supports summary/timeline/sequence/search four views
- `list_trace_files` — List local trace files
- `query_trace_file` — Query historical trace file
**Changes**
- `launch_browser` added `enable_trace` parameter, enable it automatically injects `CAMOU_CONFIG` and `MOZ_DISABLE_CONTENT_SANDBOX`
- `check_environment` added `camoufox_reverse` field, detect customized browser installation status
**Dependencies**
- Requires [camoufox-reverse](https://github.com/WhiteNightShadow/camoufox-reverse) customized browser (optional, not installed does not affect other 32 tools)
### v1.0.0（2026-04-18）— Tool Simplification + Return to Pure JS Reverse Toolset
> **Major Version**: 80 → 32 tools, schema tokens halved. Removed Session Archive/Assertion System, returned to pure JS reverse tool positioning.
**Tool Merging (v0.9.0)**
- `network_capture(action=start/stop/clear/status)` ← start/stop_network_capture
- `scripts(action=list/get/save)` ← list_scripts / get_script_source / save_script
- `search_code(keyword, script_url=None)` ← search_code / search_code_in_script
- `hook_function(path, mode=intercept/trace)` ← hook_function / trace_function
- `instrumentation(action=install/log/stop/reload/status)` ← instrument_jsvmp_source / get_instrumentation_log / stop_instrumentation / reload_with_hooks / get_instrumentation_status
- `cookies(action=get/set/delete)` ← get_cookies / set_cookies / delete_cookies
**Removed Tools**
- Session Archive System (7): start/stop_reverse_session, list_sessions, get_session_snapshot, attach_domain_readonly, export/import_session
- Assertion System (4): add/verify/list/remove_assertion
- Cold Tools (37): trace_property_access, freeze_prototype, find_dispatch_loops, get_page_content, bypass_debugger_trap, check_detection, get_fingerprint_info, dump_jsvmp_strings, evaluate_js_handle, add_init_script, set_breakpoint_via_hook, get_breakpoint_data, etc.
**New Additions**
- `verify_signer_offline` — Stateless signature function verification (replacing verify_against_session)
**Bug Fixes (v0.8.1)**
- `evaluate_js`: multi-strategy JSON parsing (control character cleaning, double encoding unpacking)
- `navigate`: default network cache cleaning, preventing cross-navigation request pollution
- `get_network_request`: `max_body_size` parameter controlling body truncation (default 5000)
- `launch_browser`: returning residual state diagnosis when already_running
**Removed Dependencies**: `tldextract` (only used for Session)
**Design Philosophy**: MCP is a pure toolset (stateless), not doing workflow management. Analysis project's memory/accumulation belongs to the skill layer and user workspace.
### v0.6.0 — Practical Bug Fixes
- `hook_jsvmp_interpreter(mode="proxy")`: fixing Proxy recursion causing `too much recursion`
- `remove_hooks`: truly restoring Proxy object
- `evaluate_js`: automatic cleaning of BOM / lone surrogate / whitespace
- `instrument_jsvmp_source`: CSP pre-check
- `navigate`: timeout elegant degradation
### v0.5.0 — Signature-type Anti-Crawling Compatibility
- `instrument_jsvmp_source` default MCP side AST rewriting
- `hook_jsvmp_interpreter` adding `mode="transparent"`
- Anti-crawling type decision table + JSVMP Playbook
### v0.4.0 — Universal JSVMP Adaptation
- Source-level instrumentation, Cookie attribution, runtime probe
- hook_jsvmp_interpreter multi-path coverage rewriting
### v0.3.0 — Stability Fixes
### v0.2.0 — Hook Persistence + JSVMP Analysis
### v0.1.0 — Initial Version (44 tools)
---
## Feedback / Communication
If you encounter bugs, want new Hook presets, or want to discuss JS reverse ideas during use, feel free to add WeChat:
- **WeChat ID**: `han8888v8888`
> Please note "camoufox-reverse" when adding friends, facilitating quick approval.
## License
MIT
