cheatengine

English | 中文

Cheat Engine MCP - AI-Assisted Reverse Engineering

MCP bridge enabling AI assistants to directly control Cheat Engine for game hacking and reverse engineering.

Architecture

AI <--MCP/JSON-RPC--> ce_mcp_server.js <--Named Pipe--> ce_mcp_bridge.lua (CE)
                           ↑
                  Background auto-reconnect

Installation

Quick Start (NPX) - Recommended

• Prerequisites: Node.js 14+ (no other dependencies needed)

• Load in CE (choose one):

  • Auto-load: Copy ce_mcp_bridge.lua to CE's autorun folder (e.g. D:\Cheat Engine\autorun\)
  • Manual: Press Ctrl+Alt+L, execute:

    dofile([[D:\path\to\ce_mcp_bridge.lua]])
    

• Configure MCP (.kiro/settings/mcp.json):

  {
    "mcpServers": {
      "cheat-engine": {
        "command": "npx",
        "args": ["--yes", "cheatengine"]
      }
    }
  }
  

Manual Installation (Local)

If you prefer to run from source:

{
  "mcpServers": {
    "cheat-engine": {
      "command": "node",
      "args": ["D:/path/to/ce_mcp/ce_mcp_server.js"]
    }
  }
}

Connection Features

• Auto-reconnect: MCP Server automatically reconnects when CE restarts
• Background retry: Connection attempts run in background with exponential backoff
• Diagnostic on failure: ce_ping returns detailed diagnostic info when connection fails
• Thread-safe: All pipe operations are protected by locks

Security Features

Authentication Token

Optional authentication layer for pipe communication. When enabled, all requests must include a valid token.

Setup:

• Set the same environment variable on both sides:

  # Windows CMD
  set CE_MCP_AUTH_TOKEN=your_secret_token_here
  
  # PowerShell
  $env:CE_MCP_AUTH_TOKEN = "your_secret_token_here"
  

• Start CE and load the bridge

• Start the MCP server

If tokens don't match, requests will be rejected with "Authentication failed" error.

Custom Pipe Name

For anti-detection, you can customize the pipe name:

set CE_MCP_PIPE_NAME=my_custom_pipe_name

Hook Name Validation

Hook names are validated to prevent AA script injection:

• Must start with letter or underscore
• Can only contain alphanumeric characters and underscores
• Pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$

Invalid names like "my hook" or "hook;inject" will be rejected.

Tool Reference

System & Connection

ce_ping

Test connection to CE bridge. Returns diagnostic info with troubleshooting suggestions on failure.

ce_get_process_info

Get attached process info and refresh symbol handler. Also clears address cache.

ce_attach_process(target)

Attach to a process by PID or name. Clears caches and scan sessions after attaching.

Parameters:

• target (string, required): Process ID (number) or process name (e.g. "game.exe")

ce_auto_assemble(script, target_self?)

Execute an Auto Assembler script. Supports enable/disable scripts, code injection, etc.

Parameters:

• script (string, required): Auto Assembler script content
• target_self (boolean, optional): Target CE process itself (default: false)

ce_execute_lua(code)

Execute arbitrary Lua code in CE.

Parameters:

• code (string, required): Lua code to execute

Memory Read/Write

ce_read_memory(address, type, size?)

Read a single memory value.

Parameters:

• address (string, required): Address expression (e.g. "game.exe+0x1234", "0x140001000")
• type (string, required): byte, word, dword, qword, float, double, string, bytes
• size (integer, optional): Size for string/bytes type (default: 100)

ce_read_memory_batch(requests)

Read multiple addresses in one call. Always prefer this over multiple ce_read_memory calls.

Parameters:

• requests (array, required): Array of {address, type, id?, size?}

ce_write_memory(address, type, value)

Write a value to memory.

Parameters:

• address (string, required): Address expression
• type (string, required): Value type
• value (string, required): Value to write

Scanning & Search

ce_aob_scan(aob_string, module?, protection?, max_results?)

Scan memory for Array of Bytes pattern. Supports ?? wildcards.

Parameters:

• aob_string (string, required): Pattern like "48 89 5C 24 ?? 48 83 EC 20"
• module (string, optional): Limit scan to module (e.g. "game.exe")
• protection (string, optional): Memory protection flags (default: "-C+X")
• max_results (integer, optional): Maximum results (default: 100)

ce_value_scan(value, type, module?, protection?)

Scan for a specific value. Useful for pointer tracing. One-shot scan - for iterative scanning use Scan Sessions.

Parameters:

• value (string, required): Value to search (e.g. "0x255D5E758" or "12345")
• type (string, required): byte, word, dword, qword, float, double, string
• module (string, optional): Limit to module
• protection (string, optional): Default "+W-C" for writable memory

Scan Sessions

Implements CE's core "First Scan → Next Scan" workflow with session management. Sessions auto-expire after 5 minutes of inactivity.

ce_scan_new(value, type, module?, protection?)

Start a new scan session.

ce_scan_next(session_id, value, scan_type?, value2?)

Continue scanning (filter) an existing session.

scan_type options:

• exact - Exact value match
• increased / decreased - Value increased/decreased
• changed / unchanged - Value changed/unchanged
• bigger_than / smaller_than - Greater/less than
• between - Between value and value2

ce_scan_results(session_id, start_index?, limit?)

Get paginated results from a scan session.

ce_scan_close(session_id)

Close a scan session and release resources.

ce_scan_list

List all active scan sessions.

ce_enum_modules

List all loaded modules (DLLs).

Symbols & Addresses

ce_get_address(expression)

Resolve address expression to numeric address.

Parameters:

• expression (string, required): e.g. "game.exe+0x1234", "[[game.exe+100]+20]+8"

ce_get_symbol(address, include_module?)

Get symbol name from address, with RTTI class info.

ce_resolve_pointer(base, offsets, read_value?, value_type?)

Resolve multi-level pointer chain with CE notation support.

Parameters:

• base (string, required): Base address or symbol (e.g. "game.exe+1234")
• offsets (array, required): Array of offsets, e.g. [0x100, 0x20, 0x8]
• read_value (boolean, optional): Read value at final address (default: false)
• value_type (string, optional): Value type (default: "dword")

Returns: Includes ceNotation (CE-compatible pointer notation) that can be directly used in CE address list.

ce_auto_guess(address)

Guess the value type at an address.

Disassembly & Code Analysis

ce_disassemble(address, count?, direction?)

Disassemble instructions.

Parameters:

• address (string, required): Start address
• count (integer, optional): Number of instructions (default: 10)
• direction (string, optional): "forward" or "backward" (default: forward)

ce_get_instruction_info(address)

Get detailed info about a single instruction.

ce_analyze_code(address, count?)

Static analysis of code block (calls, jumps, refs).

Debugging & Breakpoints

ce_set_breakpoint(address, type?, size?)

Set a hardware breakpoint.

Parameters:

• address (string, required): Address expression
• type (string, optional): "execute", "write", "access" (default: execute)
• size (integer, optional): Size for write/access breakpoints (default: 1)

ce_break_and_get_regs(address, timeout?, include_xmm?, stack_depth?)

Set breakpoint and capture registers when hit. Also returns call stack.

ce_break_and_trace(address, max_steps?, timeout?, stop_on_ret?, trace_into_call?, end_address?, initial_regs?)

Multi-step execution trace. Most powerful debugging tool - traces code execution step by step, capturing full register state at each instruction.

Parameters:

• address (string, required): Start address (breakpoint location)
• max_steps (integer, optional): Maximum instructions to trace (default: 100)
• timeout (integer, optional): Timeout in ms (default: 10000)
• stop_on_ret (boolean, optional): Stop when ret is encountered (default: true)
• trace_into_call (boolean, optional): Step into calls vs step over (default: false)
• end_address (string, optional): Stop when this address is reached
• initial_regs (object, optional): Set register values at first hit

Stop reasons: "ret", "end_address", "max_steps", "timeout"

ce_cleanup

Remove all breakpoints and traces. Use when game freezes.

Analysis Tools

ce_find_what_accesses(address, size?, duration_ms?, max_records?)

Find what code accesses this address (like CE's F5 feature). Monitors reads and writes.

ce_find_what_writes(address, size?, duration_ms?, max_records?)

Find what writes to this address (like CE's F6 feature). Monitors only writes.

ce_find_pointer_path(address, max_depth?, strategy?)

Automatic pointer chain tracing. Finds static base address for dynamic addresses.

Parameters:

• address (string, required): Dynamic address to trace
• max_depth (integer, optional): Max pointer depth 1-10 (default: 7)
• strategy (string, optional): "hybrid", "f5", "value_scan" (default: hybrid)

ce_find_references(address, limit?)

Find all code locations that reference a specific address.

ce_find_call_references(address, module?, limit?)

Find all CALL instructions that target a specific function.

ce_find_function_boundaries(address, max_search?)

Detect function start and end by analyzing prologue/epilogue patterns.

ce_generate_signature(address)

Generate unique AOB signature for an address. Useful for game updates.

Advanced Analysis

ce_build_cfg(address, max_blocks?, max_instructions?, detect_loops?)

Build Control Flow Graph for a function.

ce_detect_patterns(address, max_instructions?, patterns?)

Detect common code patterns: switch tables, virtual calls, string refs, crypto constants.

ce_compare_functions(address1, address2, max_instructions?)

Compare two functions for similarity.

ce_trace_dataflow(address, register, direction?, max_instructions?)

Trace data flow for a register within a function.

ce_program_slice(address, criterion, direction?, max_instructions?)

Compute program slice - find all instructions affecting or affected by a variable.

Code Emulation

ce_symbolic_trace(address, count?, initial_state?, stop_on_call?, stop_on_ret?)

Lightweight symbolic execution. Interprets instruction semantics without executing.

Parameters:

• address (string, required): Start address
• count (integer, optional): Instructions to trace (default: 30)
• initial_state (object, optional): Initial register symbols, e.g. {"rcx": "this_ptr", "rdx": "arg1"}

ce_call_function(address, args?, return_type?, timeout?)

Call a function in the target process. WARNING: Executes real code!

Function Hooking

ce_hook_function(address, name, capture_args?, calling_convention?)

Hook a function to intercept calls and capture arguments.

Parameters:

• address (string, required): Function address
• name (string, required): Hook identifier
• capture_args (integer, optional): Number of args to capture 0-4 (default: 4)
• calling_convention (string, optional): "auto", "fastcall", "stdcall", "cdecl"

ce_get_hook_log(name, limit?, clear?)

Get captured function call arguments.

ce_unhook_function(name)

Remove a function hook.

ce_list_hooks

List all active hooks.

Cheat Table

ce_get_address_list(include_script?)

Get all records from Cheat Table.

ce_add_address_record(description, address, value_type?, script?)

Add a new record to Cheat Table.

Recommended Workflows

Pointer Tracing

// Automatic (preferred)
{"name": "ce_find_pointer_path", "arguments": {"address": "0x255D5E758", "user_prompted": true}}
// Returns: base_address, offsets, ce_pointer_notation

// Manual (if automatic fails)
// 1. Find what accesses the address
{"name": "ce_find_what_accesses", "arguments": {"address": "0x255D5E758", "user_prompted": true}}
// 2. Get register value from result (e.g., RBX=0x255D5E658)
// 3. Search for pointer storing that value
{"name": "ce_value_scan", "arguments": {"value": "0x255D5E658", "type": "qword"}}
// 4. Repeat until finding game.exe+offset

Function Analysis

// 1. Find function boundaries
{"name": "ce_find_function_boundaries", "arguments": {"address": "0x14587EDB0"}}

// 2. Trace execution
{"name": "ce_break_and_trace", "arguments": {"address": "0x14587EDB0", "max_steps": 100}}

// 3. Generate signature for updates
{"name": "ce_generate_signature", "arguments": {"address": "0x14587EDB0"}}

Reverse Engineering Unknown Code

// 1. Disassemble
{"name": "ce_disassemble", "arguments": {"address": "0x14587EDB0", "count": 20}}

// 2. Symbolic trace to understand logic
{"name": "ce_symbolic_trace", "arguments": {"address": "0x14587EDB0", "initial_state": {"rcx": "this"}}}

// 3. Build CFG for complex functions
{"name": "ce_build_cfg", "arguments": {"address": "0x14587EDB0"}}

// 4. Detect patterns
{"name": "ce_detect_patterns", "arguments": {"address": "0x14587EDB0"}}

Troubleshooting

Issue	Solution
Connection failed	Use ce_ping - it returns diagnostic info with specific suggestions
CE restarted	MCP Server auto-reconnects, just reload the Lua script in CE
Pipe error	Run CE_MCP.stop() then CE_MCP.start() in CE
Permission denied	Run CE as administrator
Game frozen	Use ce_cleanup() to remove all breakpoints
Breakpoint not triggering	Ensure code path is executed in game

Status Check

CE_MCP.stats()  -- Check bridge status in CE
reloadMcpBridge()  -- Reload bridge after code changes

References

• CE Wiki