Back to Details

cheatengine-mcp-automation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cheat Engine MCP Automation

Cheat Engine MCP 自动化

Skill by ara.so — MCP Skills collection.
This skill enables AI agents to control Cheat Engine through the Model Context Protocol, automating memory analysis, pointer scanning, structure dissection, and reverse engineering tasks that normally take days or weeks.
由 ara.so 开发的Skill — MCP Skills 合集。
该Skill允许AI Agent通过Model Context Protocol（MCP）控制Cheat Engine，将通常需要数天或数周的内存分析、指针扫描、结构解析和逆向工程任务实现自动化。

What It Does

功能介绍

Connect Claude, Cursor, or any MCP-compatible AI to Cheat Engine for:
  • Memory scanning: Find values (int, float, string, AOB patterns) across gigabytes instantly
  • Pointer chain resolution: Follow 
    [[base+0x10]+0x20]+0x8
    paths automatically
  • Structure analysis: Auto-detect field types and offsets in memory structures
  • Code disassembly: Analyze functions, find references, identify C++ RTTI classes
  • Invisible debugging: Hardware breakpoints + Ring -1 DBVM tracing
  • Code injection: Allocate memory, inject DLLs, execute shellcode
  • Process automation: Attach, pause, resume, create processes programmatically
将Claude、Cursor或任何兼容MCP的AI连接到Cheat Engine，可实现：
  • 内存扫描：瞬间在千兆字节的内存中查找值（整数、浮点数、字符串、AOB模式）
  • 指针链解析：自动追踪
    [[base+0x10]+0x20]+0x8
    这类路径
  • 结构分析：自动检测内存结构中的字段类型和偏移量
  • 代码反汇编：分析函数、查找引用、识别C++ RTTI类
  • 隐形调试：硬件断点 + Ring -1 DBVM 追踪
  • 代码注入：分配内存、注入DLL、执行shellcode
  • 进程自动化：以编程方式附加、暂停、恢复、创建进程

Installation

安装步骤

Prerequisites

前置要求

  • Windows only (uses Named Pipes)
  • Cheat Engine 7.5+ installed
  • Python 3.10+
  • 仅支持Windows（使用命名管道）
  • 已安装Cheat Engine 7.5+
  • Python 3.10+

1. Install Python Dependencies

1. 安装Python依赖

bash
cd MCP_Server
pip install -r requirements.txt
Or manually:
bash
pip install mcp pywin32
bash
cd MCP_Server
pip install -r requirements.txt
或手动安装：
bash
pip install mcp pywin32

2. Configure MCP Server

2. 配置MCP服务器

Add to your MCP client config (location varies by client):
Claude Desktop (
~/AppData/Roaming/Claude/claude_desktop_config.json
):
json
{
  "mcpServers": {
    "cheatengine": {
      "command": "python",
      "args": ["C:/path/to/cheatengine-mcp-bridge/MCP_Server/mcp_cheatengine.py"]
    }
  }
}
Cursor (
.cursor/mcp.json
in project):
json
{
  "servers": {
    "cheatengine": {
      "command": "python",
      "args": ["C:/absolute/path/to/MCP_Server/mcp_cheatengine.py"]
    }
  }
}
Codex (
~/.codex/config.toml
):
toml
[mcp_servers.cheatengine]
command = "python"
args = ['C:\path\to\cheatengine-mcp-bridge\MCP_Server\mcp_cheatengine.py']
将以下内容添加到你的MCP客户端配置文件（位置因客户端而异）：
Claude Desktop（
~/AppData/Roaming/Claude/claude_desktop_config.json
）：
json
{
  "mcpServers": {
    "cheatengine": {
      "command": "python",
      "args": ["C:/path/to/cheatengine-mcp-bridge/MCP_Server/mcp_cheatengine.py"]
    }
  }
}
Cursor（项目中的
.cursor/mcp.json
）：
json
{
  "servers": {
    "cheatengine": {
      "command": "python",
      "args": ["C:/absolute/path/to/MCP_Server/mcp_cheatengine.py"]
    }
  }
}
Codex（
~/.codex/config.toml
）：
toml
[mcp_servers.cheatengine]
command = "python"
args = ['C:\path\to\cheatengine-mcp-bridge\MCP_Server\mcp_cheatengine.py']

3. Load Bridge in Cheat Engine

3. 在Cheat Engine中加载桥接脚本

Open Cheat Engine, then load the Lua bridge:
Option A: Execute Script (Recommended)
  1. Go to 
    File
    → 
    Execute Script
  2. Select 
    MCP_Server/ce_mcp_bridge.lua
  3. Click 
    Execute
Option B: Lua Engine
  1. Open 
    Table
    → 
    Show Cheat Table Lua Script
  2. Paste this line:
lua
dofile([[C:\path\to\cheatengine-mcp-bridge\MCP_Server\ce_mcp_bridge.lua]])
  1. Execute
Look for confirmation:
[MCP v12.0.0] MCP Server Listening on: CE_MCP_Bridge_v99
打开Cheat Engine，然后加载Lua桥接脚本：
选项A：执行脚本（推荐）
  1. 点击
    File
    → 
    Execute Script
  2. 选择
    MCP_Server/ce_mcp_bridge.lua
  3. 点击
    Execute
选项B：Lua引擎
  1. 打开
    Table
    → 
    Show Cheat Table Lua Script
  2. 粘贴以下代码：
lua
dofile([[C:\path\to\cheatengine-mcp-bridge\MCP_Server\ce_mcp_bridge.lua]])
  1. 执行脚本
查看确认信息：
[MCP v12.0.0] MCP Server Listening on: CE_MCP_Bridge_v99

4. Verify Connection

4. 验证连接

Restart your MCP client, then use the 
ping
tool:
User: "Ping cheat engine"
Expected response:
json
{
  "success": true,
  "version": "12.0.0",
  "message": "CE MCP Bridge Active",
  "process_id": 0
}
重启你的MCP客户端，然后使用
ping
工具测试：
用户："Ping cheat engine"
预期响应：
json
{
  "success": true,
  "version": "12.0.0",
  "message": "CE MCP Bridge Active",
  "process_id": 0
}

Critical Configuration

关键配置

Prevent BSODs

防止蓝屏死机（BSOD）

MUST DO: Disable this setting to prevent 
CLOCK_WATCHDOG_TIMEOUT
blue screens:
  1. Cheat Engine → 
    Edit
    → 
    Settings
  2. Go to 
    Extra
    tab
  3. UNCHECK "Query memory region routines"
  4. Restart Cheat Engine
This prevents conflicts between memory scanning and DBVM/anti-cheat systems.
必须执行：禁用以下设置以避免
CLOCK_WATCHDOG_TIMEOUT
蓝屏：
  1. 打开Cheat Engine → 
    Edit
    → 
    Settings
  2. 切换到
    Extra
    标签页
  3. 取消勾选 "Query memory region routines"
  4. 重启Cheat Engine
此设置可避免内存扫描与DBVM/反作弊系统之间的冲突。

Enable DBVM (Optional)

启用DBVM（可选）

For Ring -1 debugging and invisible breakpoints:
  1. Cheat Engine → 
    Kernel Tools
    → 
    DBVM
  2. Follow prompts to install hypervisor
  3. Reboot system
  4. DBVM functions (
    start_dbvm_watch
    , etc.) now available
如需Ring -1调试和隐形断点功能：
  1. 打开Cheat Engine → 
    Kernel Tools
    → 
    DBVM
  2. 按照提示安装虚拟机监控程序
  3. 重启系统
  4. 现在可以使用DBVM函数（如
    start_dbvm_watch
    等）

Core MCP Tools

核心MCP工具

Process Management

进程管理

lua
-- List running processes
get_process_list()
-- Returns: [{pid, name, windowTitle}, ...]

-- Attach to process
open_process({process_name = "game.exe"})
-- Or by PID: open_process({process_id = 1234})

-- Get current process info
get_process_info()
-- Returns: {name, pid, base_address, entry_point}

-- Launch new process under CE control
create_process({path = "C:/game/game.exe", parameters = "--debug"})

-- Pause/resume execution
pause_process()
unpause_process()
lua
-- 列出运行中的进程
get_process_list()
-- 返回: [{pid, name, windowTitle}, ...]

-- 附加到进程
open_process({process_name = "game.exe"})
-- 或通过PID附加: open_process({process_id = 1234})

-- 获取当前进程信息
get_process_info()
-- 返回: {name, pid, base_address, entry_point}

-- 在CE控制下启动新进程
create_process({path = "C:/game/game.exe", parameters = "--debug"})

-- 暂停/恢复进程执行
pause_process()
unpause_process()

Memory Reading

内存读取

lua
-- Read typed values
read_integer({address = "0x400000", size = 4})  -- 4-byte int
read_float({address = "0x400000", double = true})  -- 8-byte double
read_string({address = "0x400000", length = 100})  -- Read 100 chars
read_bytes({address = "0x400000", size = 16})  -- Raw bytes

-- Follow pointer chains
read_pointer_chain({
  base = "game.exe",
  offsets = [0x123456, 0x10, 0x20, 0x8]
})
-- Resolves: [[game.exe+0x123456]+0x10]+0x20]+0x8

-- Read structures
read_memory({address = "0x400000", size = 256})
lua
-- 读取指定类型的值
read_integer({address = "0x400000", size = 4})  -- 4字节整数
read_float({address = "0x400000", double = true})  -- 8字节双精度浮点数
read_string({address = "0x400000", length = 100})  -- 读取100个字符
read_bytes({address = "0x400000", size = 16})  -- 原始字节

-- 追踪指针链
read_pointer_chain({
  base = "game.exe",
  offsets = [0x123456, 0x10, 0x20, 0x8]
})
-- 解析路径: [[game.exe+0x123456]+0x10]+0x20]+0x8

-- 读取内存结构
read_memory({address = "0x400000", size = 256})

Memory Scanning

内存扫描

lua
-- Scan for specific value
scan_all({
  value = "15000",
  value_type = 4,  -- 4-byte int
  writable = true
})
-- Returns: [{address, value}, ...]

-- Next scan (filter previous results)
scan_all({
  value = "15100",
  value_type = 4,
  next_scan = true
})

-- AOB (Array of Bytes) pattern scanning
aob_scan({
  pattern = "48 8B 05 ?? ?? ?? ?? 48 85 C0",
  writable = false,
  executable = true
})

-- Find what writes to address
find_what_writes({address = "0x400000"})
-- Returns: [{instruction, address}, ...]
lua
-- 扫描特定值
scan_all({
  value = "15000",
  value_type = 4,  -- 4字节整数
  writable = true
})
-- 返回: [{address, value}, ...]

-- 后续扫描（过滤之前的结果）
scan_all({
  value = "15100",
  value_type = 4,
  next_scan = true
})

-- AOB（字节数组）模式扫描
aob_scan({
  pattern = "48 8B 05 ?? ?? ?? ?? 48 85 C0",
  writable = false,
  executable = true
})

-- 查找写入指定地址的代码
find_what_writes({address = "0x400000"})
-- 返回: [{instruction, address}, ...]

Code Analysis

代码分析

lua
-- Disassemble function
disassemble({
  address = "0x401000",
  count = 20  -- Instructions to disassemble
})

-- Analyze function structure
analyze_function({address = "0x401000"})
-- Returns: {prologue, epilogue, calls, jumps, stack_size}

-- Find all references to address
find_references({address = "0x500000"})

-- Find all CALL instructions to function
find_call_references({address = "0x401000"})

-- Get C++ class name via RTTI
get_rtti_classname({address = "0x600000"})
-- Returns: "CPlayerInventory"
lua
-- 反汇编函数
disassemble({
  address = "0x401000",
  count = 20  -- 要反汇编的指令数量
})

-- 分析函数结构
analyze_function({address = "0x401000"})
-- 返回: {prologue, epilogue, calls, jumps, stack_size}

-- 查找所有指向指定地址的引用
find_references({address = "0x500000"})

-- 查找所有调用指定函数的CALL指令
find_call_references({address = "0x401000"})

-- 通过RTTI获取C++类名
get_rtti_classname({address = "0x600000"})
-- 返回: "CPlayerInventory"

Structure Dissection

结构解析

lua
-- Auto-analyze memory structure
dissect_structure({
  address = "0x500000",
  size = 512,
  name = "PlayerData"
})
-- Returns: [
--   {offset: 0x00, type: "ptr", name: "vtable", value: "0x1234"},
--   {offset: 0x08, type: "int", name: "health", value: "100"},
--   {offset: 0x0C, type: "float", name: "x_pos", value: "123.45"}
-- ]
lua
-- 自动分析内存结构
dissect_structure({
  address = "0x500000",
  size = 512,
  name = "PlayerData"
})
-- 返回: [
--   {offset: 0x00, type: "ptr", name: "vtable", value: "0x1234"},
--   {offset: 0x08, type: "int", name: "health", value: "100"},
--   {offset: 0x0C, type: "float", name: "x_pos", value: "123.45"}
-- ]

Debugging & Breakpoints

调试与断点

lua
-- Hardware breakpoint (execution)
set_breakpoint({
  address = "0x401000",
  type = 1  -- 1=execute, 2=write, 3=access
})

-- Data breakpoint (watch memory)
set_data_breakpoint({
  address = "0x500000",
  size = 4,
  on_write = true
})

-- DBVM invisible tracing (Ring -1)
start_dbvm_watch({
  address = "0x401000",
  watch_writes = true
})

-- Remove breakpoint
remove_breakpoint({address = "0x401000"})
lua
-- 硬件断点（执行触发）
set_breakpoint({
  address = "0x401000",
  type = 1  -- 1=执行, 2=写入, 3=访问
})

-- 数据断点（监控内存）
set_data_breakpoint({
  address = "0x500000",
  size = 4,
  on_write = true
})

-- DBVM隐形追踪（Ring -1）
start_dbvm_watch({
  address = "0x401000",
  watch_writes = true
})

-- 移除断点
remove_breakpoint({address = "0x401000"})

Code Injection

代码注入

lua
-- Allocate memory in target
allocate_memory({size = 4096, near = "game.exe"})
-- Returns: {address: "0x10000000"}

-- Inject DLL
inject_dll({dll_path = "C:/mods/mymod.dll"})

-- Assemble instruction
assemble_instruction({
  instruction = "mov rax, [rbx+0x10]",
  address = "0x400000"  -- For relative addressing
})
-- Returns: {bytes: "48 8B 43 10"}

-- Execute shellcode
execute_code({
  code = "90 90 C3",  -- nop nop ret
  address = "0x10000000"
})

-- Generate API hook template
generate_api_hook_script({
  function_address = "0x401000",
  function_name = "ProcessPacket"
})
lua
-- 在目标进程中分配内存
allocate_memory({size = 4096, near = "game.exe"})
-- 返回: {address: "0x10000000"}

-- 注入DLL
inject_dll({dll_path = "C:/mods/mymod.dll"})

-- 汇编指令
assemble_instruction({
  instruction = "mov rax, [rbx+0x10]",
  address = "0x400000"  -- 用于相对寻址
})
-- 返回: {bytes: "48 8B 43 10"}

-- 执行shellcode
execute_code({
  code = "90 90 C3",  -- nop nop ret
  address = "0x10000000"
})

-- 生成API钩子模板
generate_api_hook_script({
  function_address = "0x401000",
  function_name = "ProcessPacket"
})

Symbol Management

符号管理

lua
-- Register named symbol
register_symbol({
  name = "PlayerBase",
  address = "0x500000"
})

-- Use in other commands
read_pointer_chain({
  base = "PlayerBase",
  offsets = [0x10, 0x20]
})

-- Get symbol info
get_symbol_info({name = "PlayerBase"})

-- Enable Windows PDB symbols
enable_windows_symbols()
lua
-- 注册命名符号
register_symbol({
  name = "PlayerBase",
  address = "0x500000"
})

-- 在其他命令中使用符号
read_pointer_chain({
  base = "PlayerBase",
  offsets = [0x10, 0x20]
})

-- 获取符号信息
get_symbol_info({name = "PlayerBase"})

-- 启用Windows PDB符号
enable_windows_symbols()

Common Patterns

常见使用模式

Finding Player Health

查找玩家生命值

User: "Find player health, currently at 100"

AI workflow:
1. scan_all({value: "100", value_type: 4})
2. User changes health to 95
3. scan_all({value: "95", value_type: 4, next_scan: true})
4. find_what_writes({address: first_result})
5. disassemble({address: write_instruction})
6. analyze_function({address: function_start})
用户: "查找当前为100的玩家生命值"

AI工作流:
1. scan_all({value: "100", value_type: 4})
2. 用户将生命值改为95
3. scan_all({value: "95", value_type: 4, next_scan: true})
4. find_what_writes({address: first_result})
5. disassemble({address: write_instruction})
6. analyze_function({address: function_start})

Tracing Packet Encryption

追踪数据包加密

User: "Find where network packets are encrypted"

AI workflow:
1. aob_scan({pattern: "E8 ?? ?? ?? ?? 48 8B", executable: true})
   // Common CALL pattern before crypto
2. For each result:
   - disassemble({address: result, count: 30})
   - find_call_references({address: called_function})
3. set_breakpoint({address: suspect_function, type: 1})
4. start_dbvm_watch({address: suspect_function})
用户: "查找网络数据包加密的位置"

AI工作流:
1. aob_scan({pattern: "E8 ?? ?? ?? ?? 48 8B", executable: true})
   // 加密操作前常见的CALL模式
2. 对每个结果执行:
   - disassemble({address: result, count: 30})
   - find_call_references({address: called_function})
3. set_breakpoint({address: suspect_function, type: 1})
4. start_dbvm_watch({address: suspect_function})

Understanding C++ Object

分析C++对象

User: "What is the object at [[game.exe+0x123456]+0x10]?"

AI workflow:
1. read_pointer_chain({base: "game.exe", offsets: [0x123456, 0x10]})
2. get_rtti_classname({address: result})  // "CPlayerInventory"
3. dissect_structure({address: result, size: 512, name: "CPlayerInventory"})
4. For each pointer field:
   - read_pointer_chain({base: result, offsets: [field_offset]})
   - get_rtti_classname({address: pointer_value})
用户: "[[game.exe+0x123456]+0x10]地址处的对象是什么?"

AI工作流:
1. read_pointer_chain({base: "game.exe", offsets: [0x123456, 0x10]})
2. get_rtti_classname({address: result})  // 返回"CPlayerInventory"
3. dissect_structure({address: result, size: 512, name: "CPlayerInventory"})
4. 对每个指针字段执行:
   - read_pointer_chain({base: result, offsets: [field_offset]})
   - get_rtti_classname({address: pointer_value})

Creating Update-Proof AOB

创建不受更新影响的AOB

User: "Find a unique pattern for the health function"

AI workflow:
1. find_what_writes({address: health_address})
2. disassemble({address: write_instruction, count: 50})
3. Analyze for unique opcodes (avoid relative offsets)
4. aob_scan({pattern: "48 8B 05 ?? ?? ?? ?? 48 85 C0 74 ?? 8B 40 08"})
5. Verify single result across full memory space
用户: "为生命值函数查找唯一的模式"

AI工作流:
1. find_what_writes({address: health_address})
2. disassemble({address: write_instruction, count: 50})
3. 分析唯一操作码（避免相对偏移）
4. aob_scan({pattern: "48 8B 05 ?? ?? ?? ?? 48 85 C0 74 ?? 8B 40 08"})
5. 验证在整个内存空间中仅返回单个结果

Automating Pointer Path Discovery

自动发现指针路径

lua
-- Example: Find pointer path from base to target
User: "Find the pointer chain from game.exe to 0x12345678"

AI workflow:
1. get_process_info()  // Get base address
2. scan_all({value: "0x12345678", value_type: 8})  // Find pointers to target
3. For each pointer result:
   - scan_all({value: pointer_result, value_type: 8})
4. Build chain: base -> ptr1 -> ptr2 -> target
5. register_symbol({name: "TargetPath", address: "[[game.exe+0xABC]+0x10]+0x20"})
lua
-- 示例: 从基址到目标地址查找指针链
用户: "查找从game.exe到0x12345678的指针链"

AI工作流:
1. get_process_info()  // 获取基址
2. scan_all({value: "0x12345678", value_type: 8})  // 查找指向目标的指针
3. 对每个指针结果执行:
   - scan_all({value: pointer_result, value_type: 8})
4. 构建链: base -> ptr1 -> ptr2 -> target
5. register_symbol({name: "TargetPath", address: "[[game.exe+0xABC]+0x10]+0x20"})

Real Example: Complete Game Trainer Workflow

实战示例：完整游戏修改器工作流

User: "Create a god mode for MyGame.exe"

AI session:
───────────────────────────────────────────────────
You: Attach to MyGame.exe
AI: open_process({process_name: "MyGame.exe"})
    ✓ Attached to PID 5432, base: 0x140000000

You: Find my health, currently 100
AI: scan_all({value: "100", value_type: 4})
    → Found 2,847 results

You: Took damage, now at 87
AI: scan_all({value: "87", value_type: 4, next_scan: true})
    → Filtered to 3 addresses

You: What writes to the first one?
AI: find_what_writes({address: "0x20A3B4C0"})
    → MyGame.exe+0x4F2A10 - mov [rax+08],edx

You: Disassemble that function
AI: disassemble({address: "0x1404F2A00", count: 40})
    → Found: Function processes damage, compares against max health at rax+0C

You: What's the full structure?
AI: dissect_structure({address: "0x20A3B4C0", size: 256})
    → +00: vtable
    → +08: current_health (int) = 87
    → +0C: max_health (int) = 100
    → +10: shield (int) = 0
    → +14: invulnerable (byte) = 0

You: Create a cheat to set invulnerable to 1
AI: 1. register_symbol({name: "PlayerHealth", address: "0x20A3B4C0"})
    2. Generated script:
       [ENABLE]
       PlayerHealth+14:
         db 01
       [DISABLE]
       PlayerHealth+14:
         db 00

You: Make it work after game updates
AI: aob_scan({pattern: "48 8B 05 ?? ?? ?? ?? 48 85 C0 74 ?? 89 50 08"})
    → Found unique pattern at MyGame.exe+0x4F2A0E
    Updated script with AOB injection point
用户: "为MyGame.exe创建无敌模式"

AI会话:
───────────────────────────────────────────────────
你: 附加到MyGame.exe
AI: open_process({process_name: "MyGame.exe"})
    ✓ 已附加到PID 5432, 基址: 0x140000000

你: 查找当前为100的我的生命值
AI: scan_all({value: "100", value_type: 4})
    → 找到2,847个结果

你: 受到伤害, 现在生命值为87
AI: scan_all({value: "87", value_type: 4, next_scan: true})
    → 过滤后剩下3个地址

你: 第一个地址是被什么写入的?
AI: find_what_writes({address: "0x20A3B4C0"})
    → MyGame.exe+0x4F2A10 - mov [rax+08],edx

你: 反汇编该函数
AI: disassemble({address: "0x1404F2A00", count: 40})
    → 发现: 该函数处理伤害, 与rax+0C处的最大生命值进行比较

你: 完整的结构是什么?
AI: dissect_structure({address: "0x20A3B4C0", size: 256})
    → +00: vtable
    → +08: current_health (int) = 87
    → +0C: max_health (int) = 100
    → +10: shield (int) = 0
    → +14: invulnerable (byte) = 0

你: 创建一个作弊脚本将invulnerable设为1
AI: 1. register_symbol({name: "PlayerHealth", address: "0x20A3B4C0"})
    2. 生成脚本:
       [ENABLE]
       PlayerHealth+14:
         db 01
       [DISABLE]
       PlayerHealth+14:
         db 00

你: 让它在游戏更新后依然可用
AI: aob_scan({pattern: "48 8B 05 ?? ?? ?? ?? 48 85 C0 74 ?? 89 50 08"})
    → 在MyGame.exe+0x4F2A0E处找到唯一模式
    更新脚本为AOB注入点

Environment Variables

环境变量

Set these before starting the MCP server:
bash
undefined
启动MCP服务器前设置以下变量：
bash
undefined

Increase timeout for complex operations (default: 30s)

增加复杂操作的超时时间（默认: 30秒）

set CE_MCP_TIMEOUT=60
set CE_MCP_TIMEOUT=60

Enable shell commands (SECURITY RISK - only for trusted automation)

启用shell命令（安全风险 - 仅用于可信自动化场景）

set CE_MCP_ALLOW_SHELL=1
undefined
set CE_MCP_ALLOW_SHELL=1
undefined

Troubleshooting

故障排除

"Too many local variables" error in Cheat Engine

Cheat Engine中出现"Too many local variables"错误

Solution: Use 
dofile()
instead of pasting the script:
lua
dofile([[C:\path\to\ce_mcp_bridge.lua]])
The bridge uses global functions to avoid Lua's 200 local variable limit.
解决方案: 使用
dofile()
代替粘贴脚本：
lua
dofile([[C:\path\to\ce_mcp_bridge.lua]])
桥接脚本使用全局函数以避免Lua的200个局部变量限制。

MCP client can't connect

MCP客户端无法连接

Check:
  1. Cheat Engine shows 
    MCP Server Listening on: CE_MCP_Bridge_v99
  2. MCP client restarted after config change
  3. Python path in config is absolute (not relative)
  4. pip install mcp pywin32
    completed successfully
  5. Run 
    ping
    tool - should return 
    success: true
检查事项:
  1. Cheat Engine显示
    MCP Server Listening on: CE_MCP_Bridge_v99
  2. 修改配置后已重启MCP客户端
  3. 配置中的Python路径为绝对路径（非相对路径）
  4. pip install mcp pywin32
    安装成功
  5. 运行
    ping
    工具 - 应返回
    success: true

process_id: 0
in ping response

ping响应中显示
process_id: 0

Normal - means no process attached yet. Use 
open_process()
first.
正常现象 - 表示尚未附加任何进程。先使用
open_process()
附加进程。

BSOD (CLOCK_WATCHDOG_TIMEOUT)

蓝屏死机（CLOCK_WATCHDOG_TIMEOUT）

Cause: "Query memory region routines" enabled + DBVM conflict
Fix:
  1. Cheat Engine → Settings → Extra
  2. UNCHECK "Query memory region routines"
  3. Restart Cheat Engine
原因: "Query memory region routines"已启用 + DBVM冲突
修复方法:
  1. 打开Cheat Engine → 设置 → Extra
  2. 取消勾选 "Query memory region routines"
  3. 重启Cheat Engine

Commands return 
"CE not attached"

命令返回
"CE not attached"

Solution: Attach to a process first:
lua
open_process({process_name: "target.exe"})
解决方案: 先附加到进程：
lua
open_process({process_name: "target.exe"})

DBVM functions fail

DBVM函数执行失败

Check:
  1. DBVM installed: Cheat Engine → Kernel Tools → DBVM
  2. System rebooted after DBVM install
  3. No conflicting hypervisors (Hyper-V, VMware)
检查事项:
  1. DBVM已安装: Cheat Engine → Kernel Tools → DBVM
  2. 安装DBVM后已重启系统
  3. 无冲突的虚拟机监控程序（Hyper-V、VMware）

Testing Your Setup

测试你的配置

Run the test suite to verify all ~180 tools work:
bash
cd MCP_Server
python test_mcp.py
Expected output:
✅ Memory Reading: 6/6 tests passed
✅ Process Info: 4/4 tests passed  
✅ Code Analysis: 8/8 tests passed
✅ Breakpoints: 4/4 tests passed
✅ DBVM Functions: 3/3 tests passed
✅ Utility Commands: 11/11 tests passed
────────────────────────────────────
Total: 36/37 PASSED (100% success)
运行测试套件以验证所有约180个工具正常工作：
bash
cd MCP_Server
python test_mcp.py
预期输出:
✅ 内存读取: 6/6 测试通过
✅ 进程信息: 4/4 测试通过  
✅ 代码分析: 8/8 测试通过
✅ 断点: 4/4 测试通过
✅ DBVM函数: 3/3 测试通过
✅ 实用命令: 11/11 测试通过
────────────────────────────────────
总计: 36/37 通过 (100% 成功率)

Key Value Types Reference

关键值类型参考

lua
-- value_type parameter for scanning:
1  = byte (1 byte)
2  = 2 bytes
4  = 4 bytes (int32)
8  = 8 bytes (int64)
5  = float (4 bytes)
6  = double (8 bytes)
7  = string
8  = pointer (4 or 8 bytes depending on process)
9  = AOB (array of bytes)
lua
-- 扫描时的value_type参数:
1  = byte (1字节)
2  = 2字节
4  = 4字节 (int32)
8  = 8字节 (int64)
5  = float (4字节)
6  = double (8字节)
7  = string
8  = pointer (根据进程位数为4或8字节)
9  = AOB (字节数组)

Architecture Overview

架构概述

AI Agent (Claude/Cursor/Codex)
    ↓ JSON-RPC over stdio
Python MCP Server (mcp_cheatengine.py)
    ↓ Named Pipe: \\.\pipe\CE_MCP_Bridge_v99
Lua Bridge (ce_mcp_bridge.lua)
    ↓ Cheat Engine API
Target Process Memory
The Python server translates MCP protocol to pipe commands, the Lua bridge executes them using Cheat Engine's API, and results flow back through the same chain.
AI Agent (Claude/Cursor/Codex)
    ↓ 通过标准输入输出传输JSON-RPC
Python MCP Server (mcp_cheatengine.py)
    ↓ 命名管道: \\.\pipe\CE_MCP_Bridge_v99
Lua Bridge (ce_mcp_bridge.lua)
    ↓ Cheat Engine API
目标进程内存
Python服务器将MCP协议转换为管道命令，Lua桥接脚本使用Cheat Engine的API执行命令，结果通过相同的链路返回。

Security Note

安全注意事项

This tool enables arbitrary code execution in target processes. Only use on:
  • Single-player games you own
  • Your own software for testing
  • CTF/research environments
  • Educational reverse engineering
Never use on:
  • Multiplayer games (violates ToS, ruins others' experience)
  • Software you don't have authorization to modify
  • Production systems
该工具允许在目标进程中执行任意代码。仅在以下场景使用：
  • 你拥有的单人游戏
  • 用于测试的自有软件
  • CTF/研究环境
  • 教育用途的逆向工程
绝对不要在以下场景使用：
  • 多人游戏（违反服务条款，破坏他人体验）
  • 你无权修改的软件
  • 生产系统