Perception RE MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Perception RE MCP Server scan for integer 999 in process game.exe"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Perception RE MCP Server
MCP server that bridges Claude Code to Perception.cx reverse engineering tools via AngelScript WebSocket.
Claude Code (stdio) → MCP Server (Node.js) ← WebSocket :9001 → re_server.as (Perception IDE)Multiple Claude Code instances can share the same Perception connection simultaneously through a hub/relay architecture.
Prerequisites
Node.js (v18+)
Perception.cx with AngelScript IDE
Claude Code CLI
Related MCP server: IDAssistMCP
Installation
git clone https://github.com/verifizieren/perception-mcp.git
cd perception-mcp
npm install
npm run builddist/ is gitignored - you must run npm run build after cloning or dist/index.js won't exist.
Configuration
Global (all Claude Code sessions)
Create or edit ~/.mcp.json:
{
"mcpServers": {
"perception-re": {
"command": "node",
"args": ["<full-path-to>/perception-mcp/dist/index.js"]
}
}
}Replace <full-path-to> with the absolute path to where you cloned the repo. Use forward slashes even on Windows.
Per-project
Add the same config to your project's .mcp.json in the project root.
Usage
1. Load the AngelScript server in Perception
Open re_server.as in the Perception IDE script editor and run it. The script runs in background mode - it automatically keeps trying to connect to the MCP server and reconnects if disconnected. You can load it on Perception startup.
Waiting:
[RE Server] Waiting for MCP server... (attempt 1)Connected:
[RE Server] Connected to MCP server.2. Start Claude Code
Open Claude Code in any project. The MCP server starts automatically via ~/.mcp.json.
3. Multiple instances
First instance = hub (WebSocket server on port 9001). Additional instances auto-connect as relays through the hub, sharing the one Perception connection. No extra setup.
Tools
All functionality is exposed through 9 dispatchers. Each takes an op selector plus the args for that op. This keeps the schema footprint small while covering every operation.
Dispatcher | ops |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Value types: u8 u16 u32 u64 i8 i16 i32 i64 f32 f64 (plus string wstring ptr where noted).
Notes on defaults
re_vm vadreturns compact{start,size}by default - passcompact:falsefor protection/heap_likely metadata. Always filter (min_size,heap_only,addr_*) to avoid oversized responses.re_read ptr_chainreturnsfinal_address/final_valueonly; passverbose:truefor the per-step trace.u64/i64final values come back as hex strings (JSON numbers can't hold 64 bits).re_read values/structreturnu64/i64as hex strings too; smaller ints as numbers.re_read bytescaps at 64KB unless you passraw:true(hard max 1MB) — hex payloads balloon fast.re_write valuesaccepts hex strings ("0x1122334455667788") for exact 64-bit writes; plain numbers still work for small types.re_diff diffreturns changed offsets only; passvalues:truefor per-byte a/b. Flagstruncated:trueat 1000 diffs.re_cs2 schema—filteris required (substring on field name) unless you passall:true; defaultlimit100, max 2000. Returnsname:offsetstrings.re_scan value/ptr_todefaultpage_limitis 100;countreflects the true total,has_moreflags more pages. Heavy scans have a caller-side 120s timeout — the MCP request rejects on timeout, but Perception's scan loop is not cancelled and keeps running until it finishes.
Example
You: attach to cs2.exe and show me the first 10 instructions at its entry point
Claude: [re_proc op:attach name:"cs2.exe"] [re_module op:module name:"client.dll"] [re_disasm op:disasm ...]Project Structure
perception-mcp/
├── src/
│ └── index.ts # MCP server + WebSocket hub/relay bridge + 9 dispatchers
├── re_server.as # AngelScript server for Perception IDE
├── package.json
├── tsconfig.json
└── dist/ # Built output (gitignored)
└── index.jsAPI Reference
Perception AngelScript API: https://docs.perception.cx/perception-angel-script-api/
Available Tools
9 toolsre_cs2A
CS2-specific. ops: interface {module_base,interface_name}, schema {filter?,limit?} — ALWAYS pass filter (substring match on field name, e.g. 'C_BaseEntity' or 'm_iHealth'); unfiltered schema is huge. Returns 'name:offset' strings. count=returned, total_matched=all hits.
Inputs: op (required), all, limit, filter, +2 more.
re_diffB
Snapshots & emulation. ops: dump {address,size,label}, diff {label_a,label_b,values?} (returns changed offsets; set values:true for per-byte a/b), emulate {code_address,code_size,entry_offset?,registers?,map_regions?,read_registers?,max_instructions?}
Inputs: op (required), size, label, values, +10 more.
re_disasmA
Disassembly & code analysis. ops: disasm {address,count?,size?,bytes?}, vtable {address,max_entries?,disasm_preview?}, rtti {object_address} (address of an object instance; first qword must be its vtable ptr), gensig {address,length?}, bounds {address}, analyze_fn {address,max_size?}
Inputs: op (required), size, bytes, count, +6 more.
re_moduleA
Resolve module internals. ops: module {name}, export {module_base,export_name}, import {module_base,import_name}
Inputs: op (required), name, export_name, import_name, +1 more.
re_procB
Process lifecycle & validation. ops: attach {name?|pid?}, detach {}, info {}, is_valid {address}, tebs {}
Inputs: op (required), pid, name, address.
re_readA
Read memory. ops: bytes {address,size}, values {address,type,count?}, string {address,max_length?}, wstring {address,max_length?}, ptr_chain {base,offsets[],final_type?}, struct {address,fields[]}, ptr_array {address,count,offset_delta?}, hex_dump {address,size?}, filter_ptrs {base,count,vtable_check_addr,stride?,deref_offset?}. types: u8..i64,f32,f64 (+ptr for ptr_chain).
Inputs: op (required), raw, base, size, +12 more.
re_scanA
Search process memory. ops: pattern {signature,start?,size?,module_name?} (first match), pattern_all {signature,...,max_results?}, value {type,value,heap_only?,page_offset?,page_limit?}, ptr_to {target,heap_only?,page_offset?,page_limit?}, heap_regions {regions[],type,value,max_results?,alignment?,max_total_bytes?} (chunks all regions with overlap; alignment default=val_size), xrefs {target,start?,size?,module_name?}, string_refs {search_text} (whole-process). NOTE: pattern/xrefs with no module_name/start+size scan 256MB from process base. page_limit/max_results cap RETURNED results, not scan cost. Heavy scans have a caller-side 120s timeout; the AS loop is not cancelled.
Inputs: op (required), size, type, start, +15 more.
re_vmA
Virtual memory. ops: vquery {address}, vad {heap_only?,compact?,min_size?,addr_start?,addr_end?,limit?,page_offset?} (compact defaults TRUE; paginated — default limit 500, max 5000; response has has_more/total_matched), alloc {size} (RWX), free {address}
Inputs: op (required), size, limit, address, +6 more.
re_writeA
Write memory. ops: bytes {address,data(hex)}, values {address,type,values[]}, string {address,text}, wstring {address,text}. types: u8..i64,f32,f64
Inputs: op (required), address (required), data, text, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct area of reverse engineering: module resolution, disassembly, virtual memory, snapshots/emulation, game-specific structures, memory writing, process lifecycle, memory reading, and memory scanning. Overlap is minimal and the operations within each tool are complementary.
All tools follow a consistent re_<domain> convention with clear action-oriented operations inside (e.g., attach, dump, pattern). The lower-level read/write tools share parallel op names (bytes, values, string), reinforcing predictability.
Nine tools provide a comprehensive but not bloated surface for process memory manipulation, analysis, and game-specific tasks. Each tool is substantial and earns its place; the count is well within the ideal range.
The toolkit covers process attach, memory read/write, scanning, disassembly, module internals, and advanced analysis. The primary gap is the lack of process/module enumeration, forcing agents to know or guess names/bases, which is a minor but noticeable omission for discovery workflows.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Related MCP Servers
- AlicenseAqualityBmaintenanceAn MCP server that exposes PPSSPP — the PlayStation Portable emulator — to any MCP-compatible client (Claude Desktop, Claude Code, etc.) via PPSSPP's built-in WebSocket debugger interface. Read and write PSP memory, drive games with button input, capture screenshots, set CPU breakpoints, inspect MIPS Allegrex registers — all through a clean tool interface. No bridge plugin needed; PPSSPP's debugg2329 npm13MIT
- AlicenseNot gradedqualityFmaintenanceEnables LLM clients like Claude to interact with IDA Pro for binary analysis, decompilation, cross-references, patching, and more via 41 MCP tools, 8 resources, and 7 guided prompts.50MIT
- AlicenseNot gradedqualityDmaintenanceBridges Claude Code with the Godot editor via WebSocket, enabling AI-driven game development commands such as scene tree inspection and code generation.775 npm3MIT
- FlicenseNot gradedqualityDmaintenanceConnects the x32dbg debugger to Claude AI through the Model Context Protocol, enabling natural language control of 48+ debugging operations such as breakpoints, memory analysis, and reverse engineering automation.12-