Content
# MiniApp CDP MCP
[English](https://github.com/zhizhuodemao/miniapp-cdp-mcp/blob/main/README_en.md) | English
WeChat MiniProgram reverse engineering MCP server, enabling your AI coding assistants (e.g., Claude, Cursor, Antigravity) to directly debug and analyze JavaScript code in WeChat MiniPrograms (including WeChat DevTools or PC-side MiniPrograms) via Chrome DevTools Protocol (CDP).
## Features
- **Multi-target debugging**: Supports seamless switching between `AppService` (logic layer) and `WebView` (rendering layer) targets
- **Network interception**: Captures, monitors, and filters XHR/Fetch requests initiated by MiniPrograms
- **Breakpoint debugging**: Sets/removes code breakpoints and XHR breakpoints, supporting precise location in compressed and obfuscated code
- **Execution control**: Pauses/resumes execution, step-by-step debugging (over/into/out), and returns source code context
- **Script analysis**: Lists all loaded JS scripts, searches code, retrieves/saves source code
- **Runtime inspection**: Evaluates expressions at breakpoints, inspects call stacks and scope variables
- **WebSocket analysis**: Monitors WebSocket connections and message patterns
## System Requirements
- [Python](https://www.python.org/) 3.11 or later
- [uv](https://docs.astral.sh/uv/) (required, ultra-fast Python package and environment manager)
- Running WeChat DevTools (with debugging port enabled) or PC-side WeChat MiniProgram (with remote debugging mechanism enabled)
## Prerequisites 1: Enable MiniProgram Debugging Port
Before using this MCP, you need to expose the CDP debugging port of the WeChat MiniProgram by injecting a tool. You can choose one of the following open-source tools based on your operating system and WeChat version to complete the hook and port exposure (usually exposed on port `62000`):
- [WMPFDebugger-arm](https://github.com/chain00x/WMPFDebugger-arm) (for macOS ARM architecture)
- [WMPFDebugger](https://github.com/evi0s/WMPFDebugger)
- [WeChatOpenDevTools-Python](https://github.com/JaveleyQAQ/WeChatOpenDevTools-Python)
## Prerequisites 2: Install uv
This project uses `uvx` to achieve zero-configuration "out-of-the-box" functionality. If you haven't installed `uv` yet, please execute the following commands based on your system:
**macOS / Linux:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
**Windows:**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
## Quick Start (uvx Zero-Installation)
Without cloning the code locally, you can directly utilize `uv` capabilities and add the following configuration to your AI assistant's MCP configuration file:
```json
{
"mcpServers": {
"miniapp-cdp": {
"command": "uvx",
"args": ["--from", "miniapp-cdp", "miniapp-cdp-mcp"]
}
}
}
```
### Claude Desktop
Modify `~/Library/Application Support/Claude/claude_desktop_config.json` and add the above configuration.
### Cursor
Enter `Cursor Settings` -> `Features` -> `MCP` -> `Add new MCP server`:
- **Type**: `command`
- **Name**: `miniapp-cdp`
- **Command**: `uvx --from miniapp-cdp miniapp-cdp-mcp`
## Local Installation (Optional)
If you want to modify or develop locally:
```bash
git clone https://github.com/yourusername/miniapp-cdp-py.git
cd miniapp-cdp-py
uv sync
```
Then use the local running method in the MCP configuration:
```json
{
"mcpServers": {
"miniapp-cdp": {
"command": "uv",
"args": ["run", "run_mcp_server.py"],
"cwd": "/your/path/miniapp-cdp-py"
}
}
}
```
## Tool List
### Target and Context Management
| Tool | Description |
| ----------------- | ---------------------------------------- |
| `list_targets` | Lists all available targets in the debugger (AppService threads, WebView threads, etc.) |
| `switch_target` | Switches CDP connection to different target threads for debugging context switching |
### Network and WebSocket
| Tool | Description |
| ------------------------ | ---------------------------------------------- |
| `list_network_requests` | Lists MiniProgram network requests (supports pagination), or retrieves a single request's details |
| `get_request_initiator` | Retrieves the JavaScript call stack that initiated the network request |
| `get_response_body` | Retrieves the complete response body of a network request |
| `get_websocket_messages` | Lists WebSocket connections or retrieves message details for a specific connection |
### Script Analysis
| Tool | Description |
| -------------------- | ---------------------------------------------------- |
| `list_scripts` | Lists all loaded JavaScript scripts |
| `get_script_source` | Retrieves script source code snippets, supports line ranges or character offsets |
| `save_script_source` | Saves complete script source code to a local file (suitable for extracting entire packages or core risk control code) |
| `search_in_sources` | Searches for strings or regular expressions in all scripts |
### Breakpoints and Execution Control
| Tool | Description |
| ------------------------ | ---------------------------------------------- |
| `set_breakpoint_on_text` | Automatically sets breakpoints by searching code text (avoid setting breakpoints directly on anonymous function declarations) |
| `break_on_xhr` | Sets XHR/Fetch breakpoints by URL pattern |
| `remove_breakpoints` | Removes specified breakpoints or clears all breakpoint environments with `clear_all=True` |
| `list_breakpoints` | Lists all active breakpoints |
| `get_paused_info` | Retrieves paused status, call stack, and scope variables |
| `resume_execution` | Releases breakpoints and resumes code execution |
| `step` | Step-by debugging (over/into/out), returns location and source code context |
### Inspection Tools
| Tool | Description |
| ----------------------- | ---------------------------------------------- |
| `evaluate_script` | Executes JavaScript expressions in the current context (supports execution at breakpoints) |
## Usage Examples
### Basic Process of MiniProgram Reverse Engineering
1. **Connection and Target Switching**
```
Lists all MiniProgram targets and switches to the AppService (logic layer) thread
```
2. **Finding Target Functions and Code**
```
Searches for code containing "encrypt" in all scripts and retrieves the context source code of related scripts
```
3. **Setting Breakpoints**
```
Sets breakpoints at the specific execution statements (e.g., return statements) of the encryption function
```
4. **Triggering and Analysis**
```
Triggers a network request on the MiniProgram, hits the breakpoint, and inspects parameters, call stacks, and key generation logic
```
### Intercepting and Analyzing Network Requests
```
Fetches the list of latest network requests, finds specific encrypted requests (e.g., requests with mina_edata parameters),
and then retrieves the initiator call stack to locate the encryption entry point.
```
## Practical Cases
In the project's `examples/` directory, there are some practical scripts (e.g., `vipshop_decrypt_demo.py`) that demonstrate how to analyze complex multi-layer encryption algorithms in MiniPrograms and perfectly restore them in Python.
## Security Tips
This tool exposes the underlying runtime context of MiniPrograms to the MCP client, allowing inspection, debugging, and modification of any data in the application's memory. Please do not use this tool for illegal purposes, and it is limited to personal learning, security research, and legally authorized reverse analysis.
## Acknowledgements
This project is built on top of [cdp-use](https://github.com/browser-use/cdp-use). `cdp-use` provides a highly optimized and abstracted low-level WebSocket interaction layer for Agent scenarios, greatly simplifying the communication complexity of the original CDP protocol.
## License
MIT License
