Content
# JS Reverse MCP
[English](README_en.md) | English
JavaScript reverse engineering MCP server, enabling your AI coding assistants (like Claude, Cursor, Copilot) to debug and analyze JavaScript code in web pages.
Built on top of [Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright-nodejs) protocol layer anti-detection, and optionally utilizes [CloakBrowser](https://github.com/CloakHQ/CloakBrowser) source-level fingerprint mode for strong anti-scraping sites. **Headed mode + persistent login state + zero JS injection** — appears and behaves like a real Chrome.
## Features
- **Default headed debugging**: see the browser, set breakpoints, step through, and inspect call stacks — a true reverse engineering workflow
- **Persistent login state**: cookies/localStorage preserved across sessions
- **Dual-layer anti-detection**: Patchright avoids `Runtime.enable` and `Console.enable` leakage points at the CDP protocol layer; optional `--cloak` enables CloakBrowser binary with 49 C++ source-level fingerprint patches (canvas/WebGL/audio/GPU/font)
- **Script analysis**: list all loaded JS, search code, retrieve/save source code
- **Breakpoint debugging**: set/remove breakpoints, support conditional breakpoints, and precise location in compressed code
- **Execution control**: pause/resume, step over/into/out, respond with source context
- **Runtime inspection**: evaluate expressions at breakpoints, inspect scope variables
- **Network analysis**: request call stacks, XHR breakpoints, WebSocket message analysis
## System Requirements
- [Node.js](https://nodejs.org/) v20.19 or later
- [Chrome](https://www.google.com/chrome/) stable version
## Quick Start (npx)
No installation required; simply add to your MCP client configuration:
```json
{
"mcpServers": {
"js-reverse": {
"command": "npx",
"args": ["js-reverse-mcp"]
}
}
}
```
### Claude Code
```bash
claude mcp add js-reverse npx js-reverse-mcp
```
### Codex
```bash
codex mcp add js-reverse -- npx js-reverse-mcp
```
### Cursor
Go to `Cursor Settings` -> `MCP` -> `New MCP Server`, and use the above configuration.
### VS Code Copilot
```bash
code --add-mcp '{"name":"js-reverse","command":"npx","args":["js-reverse-mcp"]}'
```
## Local Installation (optional)
```bash
git clone https://github.com/zhizhuodemao/js-reverse-mcp.git
cd js-reverse-mcp
npm install
npm run build
```
Then, use the local path in your MCP configuration:
```json
{
"mcpServers": {
"js-reverse": {
"command": "node",
"args": ["/your/path/js-reverse-mcp/build/src/index.js"]
}
}
}
```
## Anti-Detection Mechanism
This project's anti-detection mechanism is **clearly layered**. The packaging layer (this MCP itself) has **zero JS injection**, and does not perform `Object.defineProperty` hacks (which are themselves detection signals). All anti-detection measures are implemented in two non-overlapping layers:
| Layer | Default Mode | `--cloak` Mode |
| --- | --- | --- |
| **Protocol Layer** (CDP) | Patchright: avoids `Runtime.enable`/`Console.enable`, executes evaluations in isolated worlds, and removes automation launch flags | Same |
| **Source Layer** (C++ binary patches) | None — uses system Google Chrome | CloakBrowser binary (49 C++ patches: `navigator.webdriver`, canvas, WebGL, audio, GPU, font, screen, WebRTC, TLS) |
| **Profile Directory** | `~/.cache/chrome-devtools-mcp/chrome-profile` (persistent login state) | `~/.cache/chrome-devtools-mcp/cloak-profile` (physically isolated from default) |
| **Actual Browser** | Your installed Google Chrome (with Web Store, extensions, and sync) | Customized Chromium build (no Google services, no Web Store) |
Additional navigation-level measures (effective in both modes):
- **CDP silent navigation** — does not activate `Network.enable`/`Debugger.enable` during page loading; request/console collection only occurs through Playwright listeners until a tool explicitly requires CDP
- **Google Referer** — `new_page` defaults to `referer: https://www.google.com/`
- **Real viewport** — disables Playwright's default 1280×720 fake viewport; browser displays real screen size
**When to use `--cloak`**: only when the above measures are insufficient and the site is blocking your attempts. See [docs/cloak.md](docs/cloak.md) for details.
## Tool List
### Page and Navigation
| Tool | Description |
| --- | --- |
| `select_page` | List open pages or select debugging context by index |
| `new_page` | Create a new page and navigate to a URL |
| `navigate_page` | Navigate, go back, go forward, or refresh a page |
| `select_frame` | List all frames (iframes) or select execution context |
| `take_screenshot` | Capture a page screenshot |
### Script Analysis
| Tool | Description |
| --- | --- |
| `list_scripts` | List all loaded JavaScript scripts on the page |
| `get_script_source` | Retrieve script source code snippets, supporting line ranges or character offsets |
| `save_script_source` | Save complete script source code to a local file (suitable for large/compressed/WASM files) |
| `search_in_sources` | Search for strings or regular expressions in all scripts |
### Breakpoints and Execution Control
| Tool | Description |
| --- | --- |
| `set_breakpoint_on_text` | Automatically set breakpoints by searching code text (suitable for compressed code) |
| `break_on_xhr` | Set XHR/Fetch breakpoints by URL pattern |
| `remove_breakpoint` | Remove breakpoints by ID, URL, or all; automatically resume execution |
| `list_breakpoints` | List all active breakpoints |
| `get_paused_info` | Retrieve paused state, call stack, and scope variables |
| `pause_or_resume` | Toggle pause/resume execution |
| `step` | Step through code (over/into/out); returns location and source context |
### Network and WebSocket
| Tool | Description |
| --- | --- |
| `list_network_requests` | List network requests or retrieve single request details by reqid |
| `get_request_initiator` | Retrieve JavaScript call stack for network requests |
| `get_websocket_messages` | List WebSocket connections, analyze message patterns, or retrieve message details |
### Inspection Tools
| Tool | Description |
| --- | --- |
| `evaluate_script` | Execute JavaScript in the page (supports breakpoint context, main world execution, and saving results/binary data to files) |
| `list_console_messages` | List console messages or retrieve single message details by msgid |
## Usage Examples
### Basic JS Reverse Engineering Workflow
1. **Open the target page**
```
Open https://example.com and list all loaded JS scripts
```
2. **Find the target function**
```
Search for code containing "encrypt" in all scripts
```
3. **Set a breakpoint**
```
Set a breakpoint at the entry point of the encryption function
```
4. **Trigger and analyze**
```
Trigger an operation on the page; when the breakpoint is hit, inspect parameters, call stack, and scope variables
```
### WebSocket Protocol Analysis
```
List WebSocket connections, analyze message patterns, and view specific message content
```
## Configuration Options
The CLI has been deliberately simplified to 4 flags, all of which are optional. **99% of scenarios require no changes**.
| Option | Description | Default |
| --- | --- | --- |
| `--cloak` | Switch to CloakBrowser incognito binary (replaces system Chrome); adds 49 C++ source-level fingerprint patches. First launch automatically downloads ~200MB binary; fingerprint identity persists across profiles. See [docs/cloak.md](docs/cloak.md). | `false` |
| `--isolated` | Use a temporary user-data-dir (cookies/localStorage not preserved; automatically cleaned up on close) | `false` |
| `--browserUrl, -u` | Connect to an already running Chrome instance (CDP HTTP endpoint, e.g., `http://127.0.0.1:9222`). MCP will automatically detect the WebSocket debugger URL. See [docs/cdp-endpoint.md](docs/cdp-endpoint.md) for local Chrome, AdsPower, BitBrowser, etc. | – |
| `--logFile` | Path to the debugging log output file (combined with `DEBUG=*` environment variable for detailed logs) | – |
### Example Configurations
**Default — system Chrome + persistent login state** (recommended for most debugging scenarios):
```json
{
"mcpServers": {
"js-reverse": {
"command": "npx",
"args": ["js-reverse-mcp"]
}
}
}
```
**`--cloak` — for strong anti-scraping sites** (Cloudflare Turnstile/DataDome/FingerprintJS protection):
> **Highly recommended: pre-download the binary** (one-time, ~30–60 seconds). **Failure to do so** will result in the first launch with `--cloak` **silently downloading ~200MB**, appearing as if the MCP is stuck:
> ```bash
> npx cloakbrowser install
> ```
> (The `cloakbrowser` package is already installed via `optionalDependencies`; this command simply triggers its built-in binary download logic, with a progress bar)
```json
{
"mcpServers": {
"js-reverse-cloak": {
"command": "npx",
"args": ["js-reverse-mcp", "--cloak"]
}
}
}
```
**Running both configurations in parallel** — two MCP instances with physically isolated profiles, switching based on target sites:
```json
{
"mcpServers": {
"js-reverse": {
"command": "npx",
"args": ["js-reverse-mcp"]
},
"js-reverse-cloak": {
"command": "npx",
"args": ["js-reverse-mcp", "--cloak"]
}
}
}
```
**`--isolated` — new profile each time** (no cookies/localStorage preserved):
```json
{
"mcpServers": {
"js-reverse": {
"command": "npx",
"args": ["js-reverse-mcp", "--isolated"]
}
}
}
```
### Connecting to an already running Chrome/third-party fingerprint browser
`--browserUrl` only accepts **CDP endpoints** (HTTP endpoints responding to `/json/version`); not proprietary Local APIs. For local Chrome, AdsPower, BitBrowser, etc., see the dedicated documentation:
📖 **[docs/cdp-endpoint.md — How to obtain the CDP debugging port](docs/cdp-endpoint.md)**
Shortest path (local Chrome):
```bash
# Close all Chrome windows, then
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
--remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
```
```json
{
"mcpServers": {
"js-reverse": {
"command": "npx",
"args": ["js-reverse-mcp", "--browserUrl", "http://127.0.0.1:9222"]
}
}
}
```
The CDP port for fingerprint browsers (AdsPower, BitBrowser, etc.) **changes randomly on each launch**; you must use the vendor's Local API to launch the browser and then extract the port. Operation steps and example scripts are detailed in the above documentation.
## Troubleshooting
### Blocked by anti-scraping systems
If access to certain sites is blocked (e.g., Zhihu returns 40362, Cloudflare challenge loop):
1. **Try `--isolated`** — use a fresh profile to rule out residual state pollution:
```json
"args": ["js-reverse-mcp", "--isolated"]
```
2. **If that doesn't work, enable `--cloak`** — add 49 source-level fingerprint patches:
```json
"args": ["js-reverse-mcp", "--cloak"]
```
3. **Finally, consider manually clearing the persistent profile** (will lose login state):
```bash
rm -rf ~/.cache/chrome-devtools-mcp/chrome-profile
```
See [docs/cloak.md](docs/cloak.md) for guidance on when to use `--cloak` and when not to.
## Security Notice
This tool exposes browser content to the MCP client, allowing inspection, debugging, and modification of any data in the browser. **Do not use it on pages with sensitive information**.
## License
Apache-2.0
