Content
# Tool List
[中文](README.md) | [English](README_en.md)
> MCP Server based on anti-fingerprinting browser (Camoufox), supporting **universal captcha challenge auto-pass** + **JSVMP signature reduction pipeline**.
Forked from [camoufox-reverse-mcp](https://github.com/WhiteNightShadow/camoufox-reverse-mcp), with additional features:
- Built-in **captcha universal detection + auto-pass** (based on `camoufox_captcha`)
- Brand new **JSVMP offline reproduction pipeline**: WASM disassembly / Worker source code capture / WS traffic capture / offline replay + automatic diff
---
## Quick Start
### Installation
#### Method 1: Direct Installation via AI Chatbox (Recommended)
In your preferred AI coding tool (Cursor / Claude Code / Windsurf / Coze, etc.), input:
```
Help me install this MCP tool: camoufox-versatile-mcp
Project address: https://github.com/usernamexiaozhang/camoufox-versatile-mcp
```
The AI will automatically complete the following steps:
1. `git clone` or `pip install` to clone and install the project
2. Read `pyproject.toml` to confirm dependencies
3. Configure Cursor's `mcpServers` (automatically write to `settings.json`)
4. Start MCP Server and verify connection
> **Why is this method recommended?** The AI knows your operating system, Python environment, and Cursor version, and can handle path differences for Windows/macOS/Linux, automatically selecting the appropriate installation command and telling you if the installation was successful.
#### Method 2: Manual Installation
```bash
git clone https://github.com/usernamexiaozhang/camoufox-versatile-mcp
cd camoufox-versatile-mcp
pip install -e .
```
### Client Configuration (Cursor)
```json
{
"mcpServers": {
"camoufox-versatile": {
"command": "python",
"args": ["-m", "camoufox_versatile_mcp"]
}
}
}
```
### Startup Parameters
| Parameter | Description |
| --- | --- |
| `--headless` | Run in headless mode |
| `--proxy` | Proxy server, e.g., `--proxy http://127.0.0.1:7890` |
| `--geoip` | Enable GeoIP inference (automatically set geolocation based on proxy IP) |
| `--humanize` | Enable human-like mouse movement |
| `--os` | OS fingerprint: `auto` / `windows` / `macos` / `linux` |
| `--locale` | Browser language, e.g., `zh-CN` |
---
## Tool Overview (45 tools)
### Browser Control (11 tools)
| Tool | Description |
| --- | --- |
| `launch_browser` | Launch Camoufox anti-fingerprinting browser (with `i_know_what_im_doing` + `disable_coop` + `forceScopeAccess` by default) |
| `close_browser` | Close browser |
| `navigate` | Navigate to specified URL (**supports `auto_solve_challenge` parameter**) |
| `reload` | Refresh page |
| `take_screenshot` | Take screenshot |
| `take_snapshot` | Get page accessibility tree |
| `click` / `type_text` | Click element / input text |
| `wait_for` | Wait for element to appear or URL to match |
| `get_page_info` | Get current page information |
| `scroll` | Scroll page |
| `go_back` / `go_forward` | Go back / go forward |
### Universal Captcha Challenge Auto-Pass (2 tools) ⭐
| Tool | Description |
| --- | --- |
| `detect_captcha` | Detect if current page has a captcha challenge (no click) |
| `auto_solve_captcha` | Automatically detect and pass captcha challenge (`captcha_type` / `challenge_type`) |
> Supports Cloudflare's Turnstile and Interstitial modes, with reserved extension bits for `captcha_type` (hcaptcha, recaptcha, etc.).
>
> **Note**: Non-standard Cloudflare challenges (e.g., custom WAF checkbox) require additional customization.
### JS Execution and Debugging (1 tool)
| Tool | Description |
| --- | --- |
| `evaluate_js` | Execute arbitrary JS expression in page context |
### Script Analysis (2 tools)
| Tool | Description |
| --- | --- |
| `scripts(action)` | Script management: `list` / `get` / `save` |
| `search_code` | Search for keywords |
### Hooking and Tracing (4 tools)
| Tool | Description |
| --- | --- |
| `hook_function` | Hook or trace function |
| `inject_hook_preset` | Inject preset hook (xhr / fetch / crypto / websocket / debugger_bypass / cookie / runtime_probe) |
| `remove_hooks` | Remove all hooks |
| `inject_hook` | Inject custom JS hook |
### Network Analysis (5 tools)
| Tool | Description |
| --- | --- |
| `network_capture(action)` | Network capture control |
| `list_network_requests` | List captured requests |
| `get_network_request` | Get complete request details |
| `get_request_initiator` | Get JS call stack that initiated request |
| `intercept_request` | Intercept request |
### JSVMP Reverse Analysis (5 tools)
| Tool | Description |
| --- | --- |
| `hook_jsvmp_interpreter` | JSVMP runtime probe |
| `instrumentation(action)` | Source-level instrumentation |
| `compare_env` | Collect browser environment fingerprints |
| `detect_vmp` | Detect which VMP protection is used on page (obfuscated / string_eval / vm_dispatch / wasm) |
| `trace_vmp_for_sign` | Signature security tap: track which fingerprint properties VMP reads |
### Cookie and Storage (4 tools)
| Tool | Description |
| --- | --- |
| `cookies(action)` | Cookie management |
| `get_storage` | Get localStorage / sessionStorage |
| `export_state` / `import_state` | Export / import browser state |
### Verification (1 tool)
| Tool | Description |
| --- | --- |
| `verify_fingerprint` | Verify if fingerprint meets target website requirements |
### Environment Awareness (1 tool)
| Tool | Description |
| --- | --- |
| `get_env_info` | Get current browser environment information (OS, UA, screen, language, etc.) |
### JSVMP Offline Replay Pipeline (8 tools) 🆕
| Tool | Description |
| --- | --- |
| `get_tap_log` | Read `trace_vmp_for_sign` recorded tap log |
| `disassemble_wasm` | Disassemble WASM bytecode into WAT + import/export function list + entry function guess |
| `capture_worker_js` | Hijack `new Worker()` and capture blob: URL source code (direct source of JSVMP bytecode) |
| `capture_ws_payloads` | Hijack `new WebSocket()` and record all send/recv traffic |
| `auto_suggest_missing_props` | Recommend missing fingerprint props based on failed log + `trace_log` |
| `replay_vmp_offline` | Offline replay VMP code in Node sandbox (**enhanced**: supports `supplied_env` / `expected_sign` / `auto_diff`) |
| `trace_vmp_for_sign` | Signature security tap: track which fingerprint properties VMP reads |
### JS Engine Trace + HTTP Packet Trace (3 tools) 🆕
|| Tool | Description |
|| --- | --- |
|| `js_engine_trace` | JS engine tracing (three independent solutions, zero compilation, zero patch) |
|| `http_packet_trace` | HTTP packet trace (capture complete request/response + initiator JS call stack) |
|| `trace_js_and_http` | Combined mode: simultaneously enable JS trace + HTTP trace for N seconds, then automatically stop |
> Based on RuyiTrace's HttpPacketTrace idea, implemented using Playwright routing interception, without requiring RuyiTrace's C++ instrumentation.
## Captcha Challenge Auto-Pass Example
### Method 1: Automatic Challenge Pass during Navigation (Recommended)
```python
navigate(
url="https://target-site-with-captcha.com/",
auto_solve_challenge=True, # Enable auto challenge pass
challenge_type="auto", # auto detect turnstile/interstitial
challenge_ready_delay=5.0, # Wait for iframe load
expected_content_selector="#main" # Wait for main content to appear
)
```
### Method 2: Manual Tool Invocation
```python
# 1. Detect first
result = detect_captcha()
# Returns: {"url": "...", "detected": {"turnstile": True, "interstitial": False}, "challenge_present": True}
# 2. Solve
result = auto_solve_captcha(
captcha_type="cloudflare", # Currently supports cloudflare
challenge_type="auto", # auto / interstitial / turnstile
ready_delay=5.0,
solve_attempts=3,
verify=True
)
# Returns: {"solved": True, "verified": True, "challenge_type_used": "turnstile", ...}
```
---
## JSVMP Offline Replay Pipeline (Typical Process)
```
┌─────────────────────────────────────────────────────────┐
│ ① Browser-side: `trace_vmp_for_sign()` │
│ → Track which fingerprint properties VMP reads │
│ → Output prop → value list │
│ │
│ ② WASM Disassembly: `disassemble_wasm()` │
│ → Input b64/hex/wasm-url │
│ → Output WAT + imports/exports + entry function guess │
│ │
│ ③ Worker Source Code Capture: `capture_worker_js()` │
│ → Hijack `new Worker(blob:...` │
│ → Get VMP bytecode source code │
│ │
│ ④ WS Traffic Capture: `capture_ws_payloads()` │
│ → Hijack `new WebSocket()` │
│ → Record VMP bytecode request/response │
│ │
│ ⑤ Offline Replay: `replay_vmp_offline()` │
│ → Node sandbox execute VMP code │
│ → `supplied_env` inject missing fingerprint │
│ → `auto_diff` compare signature match │
│ │
│ ⑥ Missing Property Suggestion: `auto_suggest_missing_props()` │
│ → Combine `trace_log` + failed log recommend props │
│ → Output directly copyable to `supplied_env` │
└─────────────────────────────────────────────────────────┘
```
### Complete Example
```python
# Step 1: Track VMP-read properties in browser
props = trace_vmp_for_sign(
trigger_js="sign({order_id: 12345})",
wait_ms=500,
)
# Step 2: Disassemble WASM (if VMP uses WebAssembly)
wasm_info = disassemble_wasm(wasm_b64, source_kind="base64", generate_wat=True)
print(wasm_info["exports"]) # e.g. ["enc", "dec"]
print(wasm_info["entry_candidates"])
# Step 3: Offline replay (first try may not match)
result = replay_vmp_offline(
vmp_code=vmp_code,
entry="sign",
input={"order_id": 12345},
expected_sign="target_sign_value",
auto_diff=True,
)
if not result["diff"]["match"]:
# Step 4: Get suggested missing props
suggestions = auto_suggest_missing_props(
failed_replay_error=result["diff"]["replayed_preview"],
supplied_env={},
)
print(suggestions["suggestions"])
# Step 5: Replay again (with suggested env)
result = replay_vmp_offline(
vmp_code=vmp_code,
entry="sign",
input={"order_id": 12345},
expected_sign="target_sign_value",
auto_diff=True,
supplied_env={"navigator": {"userAgent": "..."}},
)
assert result["diff"]["match"]
```
---
## JS Engine Trace + HTTP Packet Trace Example
### Method 1: Combined Mode (Simplest)
```python
# Enable JS trace + HTTP trace simultaneously for 5 seconds, then automatically stop
result = trace_js_and_http(
duration=5,
trace_js=True,
trace_http=True,
trace_values=True, # Capture function parameter values
trace_dom_events=True, # Capture DOM events
capture_http_body=False, # Don't capture response body (save space)
)
# result["js_trace_summary"] → JS function call heatmap
# result["http_trace"] → HTTP request summary
```
### Method 2: Step-by-Step Control
```python
# Layer 1: Install JS source-level tracer (no special browser required)
js_engine_trace(action="install_js", max_depth=20, trace_values=True)
# Navigate to target page and trigger JS
navigate("https://target-site.com/api/sign")
# Read trace result
result = js_engine_trace(action="read", session_id="abc12345")
# → hot_functions, depth_histogram, sample_events
# Layer 2: HTTP packet trace
http_packet_trace(action="start", capture_body=True)
# Trigger target request
await page.evaluate("fetch('/api/sign', {method:'POST', body: JSON.stringify({a:1})})")
# Read HTTP trace
http_result = http_packet_trace(action="read")
```
# → api_requests, javascript_requests, slow_requests
```
### Method Three: CDP DevTools Native Tracer (requires remote_debugging_port)
```python
# Launch browser with remote debugging
launch_browser(remote_debugging_port=9222)
# Start CDP native tracer (Firefox built-in JS ExecutionTracer)
js_engine_trace(
action="start_cdp",
trace_values=True,
trace_dom_events=True,
trace_dom_mutations=False,
max_records=50000,
cdp_port=9222,
)
```
## Technical Architecture
```
┌─────────────────────────────────────────────────┐
│ AI Coding Assistant (Cursor / Claude) │
│ MCP (stdio) │
├─────────────────────────────────────────────────┤
│ camoufox-versatile-mcp │
│ ┌──────────┬──────────┬──────────┬──────────┐ │
│ │Navigation│ Script │Debugging │ Hooking │ │
│ ├──────────┼──────────┼──────────┼──────────┤ │
│ │ Network │ JSVMP │ Cookie │ Verify │ │
│ ├──────────┼──────────┼──────────┼──────────┤ │
│ │ ★ Captcha Auto-Solve (cloudflare) │ │
│ │ ★ JSVMP Pipeline (WASM/Worker/WS/Replay) │ │
│ └──────────┴──────────┴──────────┴──────────┘ │
│ Playwright API │
├─────────────────────────────────────────────────┤
│ Camoufox (Anti-fingerprinting Firefox, Juggler protocol) │
└─────────────────────────────────────────────────┘
```
## License
MIT
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available