HollyZoe/cheatengine-mcp-tcp-bridge
GitHub: HollyZoe/cheatengine-mcp-tcp-bridge
HollyZoe/cheatengine-mcp-tcp-bridge：通过TCP协议将Cheat Engine与AI代理连接，实现自动化逆向工程。
Stars: 7 | Forks: 0
**[英语](README.md) | [中文](README_CN.md)**
[演示](https://github.com/user-attachments/assets/a184a006-f569-4b55-858a-ed80a7139035)
# Cheat Engine MCP Bridge (TCP增强分支)
**让数十亿美元的AI数据中心为您分析程序内存。**
创建模组、训练器、安全审计、游戏机器人、加速RE，或者用任何程序和游戏在极短的时间内做任何其他事情。
[](#) [](https://python.org) [-orange.svg)](#)
## 问题
您面对着数GB的内存。数百万个地址。数千个函数。找到“那个指针”，“那个结构”需要**几天或几周的手动工作**。
**如果您能直接询问会怎样呢？**
**这正是它所做的事情。**
_- 停止点击十六进制转储，开始与内存进行对话。_
## 您将获得：
| 之前（手动） | 之后（AI代理+MCP） |
|--------------|---------------------|
| 第1天：找到数据包地址 | 第1分钟：“找到RX数据包解密钩子” |
| 第2天：跟踪写入它的内容 | 第3分钟：“生成唯一的AOB签名以使其更新持久” |
| 第3天：找到RX钩子 | 第6分钟：“找到移动OPcodes” |
| 第4天：记录结构 | 第10分钟：“创建十六进制到纯文本的python解释器” |
| 第5天：游戏更新，重新开始 | **完成。** |
**您的AI现在可以：**
- 瞬间读取任何内存（整数、浮点数、字符串、指针）
- 跟踪指针链：`[[base+0x10]+0x20]+0x8` → 毫秒内解析
- 自动分析具有字段类型和值的结构
- 通过RTTI识别C++对象：*"这是一个CPlayer对象"*
- 反汇编和分析函数
- 使用硬件断点和Ring -1虚拟机调试器无痕调试
- 通过TCP连接到**本地或远程**Cheat Engine实例
- 以及更多！
## 工作原理
```
flowchart TD
AI[AI Agent: Claude/Cursor/Copilot]
AI -->|MCP Protocol - JSON-RPC over stdio| MCP
MCP[mcp_cheatengine.py - Python MCP Server]
MCP <-->|"TCP Socket (port 17171+)"| DLL
subgraph CE[Cheat Engine]
subgraph DLL_BLOCK[ce_mcp_tcp.dll - Native TCP Bridge]
DLL[TCP Server Thread
Winsock2 + select] end subgraph LUA[ce_mcp_bridge.lua] POLL[Timer Poll Loop
10ms interval] CMD[Command Handlers
~180 tools] end DLL <-->|"Lua C API
poll/respond"| POLL POLL --> CMD end CMD -->|CE API| TARGET[Target Process] ``` ### 传输模式 | 模式 | 协议 | 用例 | |------|----------|----------| | **TCP** (默认) | 本地DLL TCP服务器在端口17171+ | 本地和远程，稳定重连 | | **Pipe** (旧版/已弃用) | Windows命名管道 | 仅本地，需要`pywin32` | TCP模式使用由Lua桥通过`package.loadlib`加载的本地C DLL (`ce_mcp_tcp_x64.dll` / `ce_mcp_tcp_x86.dll`)。DLL处理所有Winsock TCP通信；Lua在10ms定时器上轮询命令并分发响应。Lua中没有Winsock FFI或kernel32引导。 ## 前置条件 | 要求 | 版本 | 备注 | |-------------|---------|-------| | **Python** | 3.10+ | 用于MCP服务器 | | **Cheat Engine** | 7.5+ | 推荐使用7.6；DBVM功能需要启用DBVM构建 | | **本地TCP DLL** | v2.0.0 | `ce_mcp_tcp_x64.dll`或`ce_mcp_tcp_x86.dll`在CE可执行文件目录中 | | **pip包`mcp`** | 最新版 | `pip install mcp` | | **Git** | 任何版本 | 用于克隆存储库 | ## 安装 ### 步骤1：克隆存储库 ``` git clone https://github.com/HollyZoe/cheatengine-mcp-tcp-bridge.git cd cheatengine-mcp-tcp-bridge ``` ### 步骤2：安装Python依赖项 ``` pip install -r MCP_Server/requirements.txt ``` 或手动安装： ``` pip install mcp ``` ### 步骤3：将本地TCP DLL放置在Cheat Engine的目录中 从`MCP_Server/`复制与架构匹配的DLL到**与您的Cheat Engine可执行文件相同的文件夹**（例如，`cheatengine-x86_64.exe`所在的文件夹）： | CE构建 | 要复制的DLL | |----------|-------------| | 64位 | `ce_mcp_tcp_x64.dll` | | 32位 | `ce_mcp_tcp_x86.dll` | 示例（64位CE安装在`C:\CE 7.5`）： ``` C:\CE 7.5\cheatengine-x86_64.exe C:\CE 7.5\ce_mcp_tcp_x64.dll ← copy here ``` 预构建的二进制文件也位于`NativeBridge/bin/x64/`和`NativeBridge/bin/x86/`，如果您从源代码重新构建。 ## 快速入门 ### 步骤1：在Cheat Engine中附加进程 1. 打开Cheat Engine。 2. 点击左上角的**计算机图标**以打开进程列表。 3. 选择并附加到您的目标进程（例如，游戏或应用程序）。 4. *(可选)* 如果您计划使用DBVM工具（硬件断点，Ring -1跟踪），启用DBVM：`DBVM` → `启用DBVM`。 ### 步骤2：加载MCP桥接脚本 有两种方法可以加载桥接： **方法A — 执行脚本（推荐**） 1. 在Cheat Engine中：`文件` → `执行脚本` 2. 浏览到并打开`MCP_Server/ce_mcp_bridge.lua` 3. 点击`执行` **方法B — Cheat Table脚本（后备**） 1. 在Cheat Engine中：`表` → `显示作弊表Lua脚本` 2. 粘贴以下行（更新为您的实际路径）： ``` dofile([[C:\path\to\cheatengine-mcp-tcp-bridge\MCP_Server\ce_mcp_bridge.lua]]) ``` 3. 点击`执行` **Cheat Engine Lua输出窗口中的预期输出：** ``` [MCP] CE path: C:\path\to\CE 7.5 [MCP] CE x64 - loading ce_mcp_tcp_x64.dll [MCP] DLL loaded OK from: C:\path\to\CE 7.5\ce_mcp_tcp_x64.dll [MCP] Bridge started on port 17171 (native mode) - you can close this window now. ``` 一个**单独的DLL调试控制台**也打开了，其中包含诊断输出： ``` [MCP-DLL] ce_mcp_tcp.dll loaded (v2.0.0) [MCP-DLL] luaopen_ce_mcp_tcp called [MCP-DLL] Resolving Lua API (17 functions)... [MCP-DLL] Found module: lua53-64.dll [MCP-DLL] lua53-64.dll => 17/17 functions [MCP-DLL] Native mode: 5 Lua functions registered [MCP-DLL] mcp_tcp_start called [MCP-DLL] TCP server thread started [MCP-DLL] Listening on 0.0.0.0:17171 (mode: Lua API) ``` ### 步骤3：配置您的AI客户端 选择您的AI客户端以下并添加MCP服务器配置。
### 步骤4：验证连接
在您的AI聊天中，让AI验证连接。它将自动使用`ping`工具：
```
You: "Ping the Cheat Engine bridge"
```
预期响应：
```
{"success": true, "version": "15.0.0", "message": "CE MCP Bridge v15.0.0 alive"}
```
### 步骤5：开始使用
现在您可以与AI交谈，它将通过Cheat Engine与目标进程交互：
```
You: "What process is attached?"
You: "Read 16 bytes at the base address of the main module"
You: "Disassemble the entry point of the main module"
You: "Scan for the integer value 99999"
You: "What's the RTTI class name at [[game.exe+0x1234]+0x10]?"
```
## 180个MCP工具可用
### 内存
| 工具 | 描述 |
|------|-------------|
| `read_memory`，`read_integer`，`read_string` | 读取任何数据类型 |
| `read_pointer_chain` | 跟踪`[[base+0x10]+0x20]`路径 |
| `scan_all`，`aob_scan` | 查找值和字节模式 |
### 分析
| 工具 | 描述 |
|------|-------------|
| `disassemble`，`analyze_function` | 代码分析 |
| `dissect_structure` | 自动检测字段和类型 |
| `get_rtti_classname` | 识别C++对象类型 |
| `find_references`，`find_call_references` | 交叉引用 |
### 调试
| 工具 | 描述 |
|------|-------------|
| `set_breakpoint`，`set_data_breakpoint` | 硬件断点 |
| `start_dbvm_watch` | Ring -1不可见跟踪 |
### 进程生命周期
| 工具 | 描述 |
|------|-------------|
| `open_process`，`get_process_list` | 附加到或枚举正在运行的进程 |
| `create_process` | 在CE的控制下启动新进程 |
| `pause_process`，`unpause_process` | 暂停/恢复目标执行 |
### 内存分配
| 工具 | 描述 |
|------|-------------|
| `allocate_memory`，`free_memory` | 在目标中保留和释放内存 |
| `set_memory_protection`，`full_access` | 调整页面保护标志 |
### 代码注入
| 工具 | 描述 |
|------|-------------|
| `inject_dll` | 将DLL加载到目标进程 |
| `execute_code`，`execute_method` | 远程运行shellcode或CE Lua方法 |
### 符号管理
| 工具 | 描述 |
|------|-------------|
| `register_symbol`，`get_symbol_info` | 创建和查询命名符号 |
| `enable_windows_symbols` | 启用PDB符号解析 |
### 汇编/编译
| 工具 | 描述 |
|------|-------------|
| `assemble_instruction` | 将单个x86/x64指令汇编为字节 |
| `compile_c_code` | 将C源代码编译为注入的shellcode |
| `generate_api_hook_script` | 生成CE自动汇编器API钩子模板 |
### 窗口/GUI自动化
| 工具 | 描述 |
|------|-------------|
| `find_window` | 通过标题或类定位窗口 |
| `send_window_message` | 向目标窗口发送`WM_*`消息 |
### 输入自动化
| 工具 | 描述 |
|------|-------------|
| `get_pixel` | 在屏幕坐标处采样像素颜色 |
| `is_key_pressed`，`do_key_press` | 查询和模拟键盘输入 |
### 作弊表
| 工具 | 描述 |
|------|-------------|
| `load_table`，`save_table` | 加载/保存`.CT`作弊表文件 |
| `get_address_list` | 枚举活动作弊表中的条目 |
### 内核模式（DBK/DBVM）
| 工具 | 描述 |
|------|-------------|
| `dbk_get_cr3` | 读取目标进程的CR3寄存器 |
| `read_process_memory_cr3` | 通过CR3绕过读取物理内存 |
还有更多在`AI_Context/MCP_Bridge_Command_Reference.md`中。
## 环境变量
| 变量 | 默认值 | 目的 |
|----------|---------|---------|
| `CE_TRANSPORT` | `tcp` | 传输模式：`tcp`（推荐）或`pipe`（旧版/已弃用）。 |
| `CE_HOST` | `127.0.0.1` | Cheat Engine实例的TCP主机地址。对于远程调试，设置为远程IP地址。 |
| `CE_PORT` | `17171` | TCP基本端口。如果端口被占用，DLL将自动递增。 |
| `CE_PORT_RANGE` | `10` | 从`CE_PORT`开始扫描的端口号数。Python客户端尝试每个端口，并通过`ping`验证CE桥接器。 |
| `CE_MCP_TIMEOUT` | `90` | 每个MCP工具调用的超时时间（秒）。设置为`0`以禁用。 |
| `CE_MCP_ALLOW_SHELL` | *未设置* | 将其设置为`1`以启用`run_command`/`shell_execute`工具。**任意代码执行风险** — 默认不设置。 |
## TCP架构细节
### 本地TCP桥接DLL (`ce_mcp_tcp_x64.dll` / `ce_mcp_tcp_x86.dll`)
一个编译的C DLL（v2.0.0）处理所有TCP通信。它替换了Lua中之前的Winsock FFI实现。
| 方面 | 详细信息 |
|--------|--------|
| **加载** | Lua通过`package.loadlib`从CE可执行文件目录加载DLL |
| **Lua API** | DLL从CE目录中的`lua53-64.dll`（或类似）动态解析17个Lua C API函数 |
| **注册的函数** | `mcp_tcp_start`，`mcp_tcp_stop`，`mcp_tcp_poll`，`mcp_tcp_respond`，`mcp_tcp_status` |
| **构建** | 使用`/MT`（静态CRT）编译 — 无需Visual C++运行时 redistributable |
| **日志记录** | 打开一个单独的调试控制台窗口（`[MCP-DLL]`前缀） |
| **后备** | 当Lua API无法解析时，使用文件IPC模式（请参阅DLL调试控制台） |
**DLL TCP服务器流程：**
1. **绑定和监听** — 绑定到`0.0.0.0:17171`（如果端口被占用，则自动递增），TCP服务器线程使用Winsock2 + `select()`。
2. **接受和接收** — 每次接受一个客户端，接收帧化的JSON-RPC请求。
3. **队列到Lua** — 进来的命令被排队；Lua的10ms定时器调用`mcp_tcp_poll`以出队。
4. **在主线程上执行** — Lua命令处理程序运行CE API调用（与之前相同 ~180 个工具）。
5. **响应** — Lua调用`mcp_tcp_respond`以JSON结果；DLL发送长度前缀的UTF-8有效负载。
6. **帧化** — 4字节小端长度前缀 + UTF-8 JSON-RPC有效负载（自v14以来未更改）。
### CE Lua桥接器 (`ce_mcp_bridge.lua`)
Lua脚本薄加载器和命令分发器（~1000行已删除的FFI/Winsock/Pipe代码）：
1. 解析CE安装路径并加载正确的架构DLL。
2. 调用`mcp_tcp_start(port)`以启动本地TCP服务器。
3. 创建一个**10ms定时器**，轮询`mcp_tcp_poll`，将命令分发给处理程序，并调用`mcp_tcp_respond`。
4. 没有Winsock FFI，没有kernel32引导，没有`getAddressSafe`依赖项。
### Python客户端 (`mcp_cheatengine.py`)
- **端口扫描** — 尝试端口`CE_PORT`通过`CE_PORT + CE_PORT_RANGE - 1`，通过`ping`命令验证每个端口以确保它是CE桥接器（不是其他服务）。
- **自动重连** — 如果连接断开，下一个命令将自动重连。
- **线程安全** — `threading.Lock()`序列化来自MCP框架的并发工具调用。
- **超时保护** — 每个调用可配置的超时时间，自动清理套接字。
### 端口自动递增
如果默认端口（17171）被占用，**DLL**将自动递增（与v14相同，现在在本地代码中）：
| 场景 | CE服务器端口 | Python客户端行为 |
|----------|---------------|----------------------|
| 单个CE实例 | 17171 | 直接连接 |
| 端口17171被占用（例如，另一个CE） | 17172 | 扫描17171-17180，找到CE在17172 |
| 两个CE实例 | 17171，17172 | 连接到找到的第一个CE桥接器 |
## 远程Cheat Engine设置
要控制另一台机器上的Cheat Engine实例：
1. **网络** — 确保TCP端口17171可到达（防火墙、VPN等）。
2. **CE端** — 将DLL复制到远程CE目录，然后执行`ce_mcp_bridge.lua`。服务器默认绑定到`0.0.0.0
Winsock2 + select] end subgraph LUA[ce_mcp_bridge.lua] POLL[Timer Poll Loop
10ms interval] CMD[Command Handlers
~180 tools] end DLL <-->|"Lua C API
poll/respond"| POLL POLL --> CMD end CMD -->|CE API| TARGET[Target Process] ``` ### 传输模式 | 模式 | 协议 | 用例 | |------|----------|----------| | **TCP** (默认) | 本地DLL TCP服务器在端口17171+ | 本地和远程，稳定重连 | | **Pipe** (旧版/已弃用) | Windows命名管道 | 仅本地，需要`pywin32` | TCP模式使用由Lua桥通过`package.loadlib`加载的本地C DLL (`ce_mcp_tcp_x64.dll` / `ce_mcp_tcp_x86.dll`)。DLL处理所有Winsock TCP通信；Lua在10ms定时器上轮询命令并分发响应。Lua中没有Winsock FFI或kernel32引导。 ## 前置条件 | 要求 | 版本 | 备注 | |-------------|---------|-------| | **Python** | 3.10+ | 用于MCP服务器 | | **Cheat Engine** | 7.5+ | 推荐使用7.6；DBVM功能需要启用DBVM构建 | | **本地TCP DLL** | v2.0.0 | `ce_mcp_tcp_x64.dll`或`ce_mcp_tcp_x86.dll`在CE可执行文件目录中 | | **pip包`mcp`** | 最新版 | `pip install mcp` | | **Git** | 任何版本 | 用于克隆存储库 | ## 安装 ### 步骤1：克隆存储库 ``` git clone https://github.com/HollyZoe/cheatengine-mcp-tcp-bridge.git cd cheatengine-mcp-tcp-bridge ``` ### 步骤2：安装Python依赖项 ``` pip install -r MCP_Server/requirements.txt ``` 或手动安装： ``` pip install mcp ``` ### 步骤3：将本地TCP DLL放置在Cheat Engine的目录中 从`MCP_Server/`复制与架构匹配的DLL到**与您的Cheat Engine可执行文件相同的文件夹**（例如，`cheatengine-x86_64.exe`所在的文件夹）： | CE构建 | 要复制的DLL | |----------|-------------| | 64位 | `ce_mcp_tcp_x64.dll` | | 32位 | `ce_mcp_tcp_x86.dll` | 示例（64位CE安装在`C:\CE 7.5`）： ``` C:\CE 7.5\cheatengine-x86_64.exe C:\CE 7.5\ce_mcp_tcp_x64.dll ← copy here ``` 预构建的二进制文件也位于`NativeBridge/bin/x64/`和`NativeBridge/bin/x86/`，如果您从源代码重新构建。 ## 快速入门 ### 步骤1：在Cheat Engine中附加进程 1. 打开Cheat Engine。 2. 点击左上角的**计算机图标**以打开进程列表。 3. 选择并附加到您的目标进程（例如，游戏或应用程序）。 4. *(可选)* 如果您计划使用DBVM工具（硬件断点，Ring -1跟踪），启用DBVM：`DBVM` → `启用DBVM`。 ### 步骤2：加载MCP桥接脚本 有两种方法可以加载桥接： **方法A — 执行脚本（推荐**） 1. 在Cheat Engine中：`文件` → `执行脚本` 2. 浏览到并打开`MCP_Server/ce_mcp_bridge.lua` 3. 点击`执行` **方法B — Cheat Table脚本（后备**） 1. 在Cheat Engine中：`表` → `显示作弊表Lua脚本` 2. 粘贴以下行（更新为您的实际路径）： ``` dofile([[C:\path\to\cheatengine-mcp-tcp-bridge\MCP_Server\ce_mcp_bridge.lua]]) ``` 3. 点击`执行` **Cheat Engine Lua输出窗口中的预期输出：** ``` [MCP] CE path: C:\path\to\CE 7.5 [MCP] CE x64 - loading ce_mcp_tcp_x64.dll [MCP] DLL loaded OK from: C:\path\to\CE 7.5\ce_mcp_tcp_x64.dll [MCP] Bridge started on port 17171 (native mode) - you can close this window now. ``` 一个**单独的DLL调试控制台**也打开了，其中包含诊断输出： ``` [MCP-DLL] ce_mcp_tcp.dll loaded (v2.0.0) [MCP-DLL] luaopen_ce_mcp_tcp called [MCP-DLL] Resolving Lua API (17 functions)... [MCP-DLL] Found module: lua53-64.dll [MCP-DLL] lua53-64.dll => 17/17 functions [MCP-DLL] Native mode: 5 Lua functions registered [MCP-DLL] mcp_tcp_start called [MCP-DLL] TCP server thread started [MCP-DLL] Listening on 0.0.0.0:17171 (mode: Lua API) ``` ### 步骤3：配置您的AI客户端 选择您的AI客户端以下并添加MCP服务器配置。
Cursor IDE
将以下内容添加到您的项目`.cursor/mcp.json`（或全局`~/.cursor/mcp.json`）： ``` { "mcpServers": { "cheatengine": { "command": "python", "args": ["C:/path/to/cheatengine-mcp-tcp-bridge/MCP_Server/mcp_cheatengine.py"], "env": { "CE_TRANSPORT": "tcp", "CE_HOST": "127.0.0.1", "CE_PORT": "17171" } } } } ``` 保存后，**重新启动Cursor**（或重新加载设置中的MCP服务器）以应用配置。Claude Desktop
将以下内容添加到`%APPDATA%\Claude\claude_desktop_config.json`（Windows）或`~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）： ``` { "mcpServers": { "cheatengine": { "command": "python", "args": ["C:/path/to/cheatengine-mcp-tcp-bridge/MCP_Server/mcp_cheatengine.py"], "env": { "CE_TRANSPORT": "tcp", "CE_HOST": "127.0.0.1", "CE_PORT": "17171" } } } } ``` 保存后，重新启动Claude Desktop。Codex CLI
在`~/.codex/config.toml`中添加一个TOML服务器块： ``` [mcp_servers.cheatengine] command = "python" args = ['C:\path\to\cheatengine-mcp-tcp-bridge\MCP_Server\mcp_cheatengine.py'] ``` 在Windows路径中使用单引号，以便TOML将反斜杠视为字面量。远程Cheat Engine（不同机器）
将`CE_HOST`更改为远程机器的IP地址： ``` { "env": { "CE_TRANSPORT": "tcp", "CE_HOST": "192.168.1.100", "CE_PORT": "17171" } } ``` **CE机器上的防火墙设置：** ``` # Windows 防火墙 — 允许入站 TCP 17171 netsh advfirewall firewall add rule name="CE MCP Bridge" dir=in action=allow protocol=TCP localport=17171 # Linux（如适用） sudo ufw allow 17171/tcp ```标签：AI辅助, Cheat Engine, C++对象识别, JARM, Python开发, rizin, TCP通信, 云资产清单, 内存分析, 函数分析, 指针扫描, 数据结构分析, 游戏作弊, 生成式AI安全, 硬件断点, 虚拟机, 逆向工具, 逆向工程