Skip to content
Back to search

cheatengine-mcp-bridge

Connect your favorite AI agents directly to Cheat Engine via MCP. Automate reverse engineering, pointer scanning, and memory analysis using natural language.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/miscusi-peek--cheatengine-mcp-bridge/badge.svg)](/listings/miscusi-peek--cheatengine-mcp-bridge)

HTML

<a href="/listings/miscusi-peek--cheatengine-mcp-bridge"><img src="/api/listings/miscusi-peek--cheatengine-mcp-bridge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install -r MCP_Server/requirements.txt

Or manually:

pip install mcp pywin32

> [!NOTE] > Native pipe mode is **Windows only** because it uses Named Pipes (`pywin32`). Use TCP relay transport when the MCP server runs outside the Windows environment that hosts Cheat Engine and cannot open the named pipe directly.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 384 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. [Demo](https://github.com/user-attachments/assets/a184a006-f569-4b55-858a-ed80a7139035)
  2. # Cheat Engine MCP Bridge
  3. **Let multibillion $ AI datacenters analyze the program memory for you.**
  4. Create mods, trainers, security audits, game bots, accelerate RE, or do anything else with any program and game in a fraction of a time.
  5. [![Version](https://img.shields.io/badge/version-12.0.0-blue.svg)](#) [![Python](https://img.shields.io/badge/python-3.10%2B-green.svg)](https://python.org)
  6. > [!NOTE]
  7. > Thanks everyone for the stars, much appreciated! <3
  8. >
  9. > Specially a big thank you to all the contributors!!
  10. >
  11. > [@libangli218](https://github.com/libangli218), [@lauralex](https://github.com/lauralex), [@iamtyroon](https://github.com/iamtyroon), [@HachiroSan](https://github.com/HachiroSan), [@Attacktive](https://github.com/Attacktive)
  12. ---
  13. ## The Problem
  14. You're staring at gigabytes of memory. Millions of addresses. Thousands of functions. Finding *that one pointer*, *that one structure* takes **days or weeks** of manual work.
  15. **What if you could just ask?**
  16. > *"Find the packet decryptor hook."*
  17. > *"Find the OPcode of character coordinates."*
  18. > *"Find the OPcode of health values."*
  19. > *"Find the unique AOB pattern to make my trainer reliable after game updates."*
  20. **That's exactly what this does.**
  21. _- Stop clicking through hex dumps and start having conversations with the memory._
  22. ---
  23. ## What You Get:
  24. | Before (Manual) | After (AI Agent + MCP) |
  25. |-----------------|---------------------|
  26. | Day 1: Find packet address | Minute 1: "Find RX packet decryption hook" |
  27. | Day 2: Trace what writes to it | Minute 3: "Generate unique AOB signature to make it update persistent" |
  28. | Day 3: Find RX hook | Minute 6: "Find movement OPcodes" |
  29. | Day 4: Document structure | Minute 10: "Create python interpreter of hex to plain text" |
  30. | Day 5: Game updates, start over | **Done.** |
  31. **Your AI can now:**
  32. - Read any memory instantly (integers, floats, strings, pointers)
  33. - Follow pointer chains: `[[base+0x10]+0x20]+0x8` → resolved in ms
  34. - Auto-analyze structures with field types and values
  35. - Identify C++ objects via RTTI: *"This is a CPlayer object"*
  36. - Disassemble and analyze functions
  37. - Debug invisibly with hardware breakpoints + Ring -1 hypervisor
  38. - And much more!
  39. ---
  40. ## How It Works
  41. ```mermaid
  42. flowchart TD
  43. AI[AI Agent: Claude/Cursor/Copilot]
  44. AI -->|MCP Protocol - JSON-RPC over stdio| MCP
  45. MCP[mcp_cheatengine.py - Python MCP Server]
  46. MCP <-->|Named Pipe - Async| PIPE
  47. PIPE["\\.\\pipe\\CE_MCP_Bridge_v99"]
  48. PIPE <--> CE
  49. subgraph CE[Cheat Engine - DBVM Mode]
  50. subgraph LUA[ce_mcp_bridge.lua]
  51. WORKER[Worker Thread - Blocking I/O]
  52. MAIN[Main Thread - GUI + CE API]
  53. WORKER <-->|Sync| MAIN
  54. end
  55. end
  56. MAIN -->|Memory Access| TARGET[Target .exe]
  57. ```
  58. ---
  59. ## Installation
  60. ```bash
  61. pip install -r MCP_Server/requirements.txt
  62. ```
  63. Or manually:
  64. ```bash
  65. pip install mcp pywin32
  66. ```
  67. > [!NOTE]
  68. > Native pipe mode is **Windows only** because it uses Named Pipes (`pywin32`). Use TCP relay transport when the MCP server runs outside the Windows environment that hosts Cheat Engine and cannot open the named pipe directly.
  69. ---
  70. ## Quick Start
  71. ### 1. Load Bridge in Cheat Engine
  72. 1. Enable DBVM in Cheat Engine if you plan to use DBVM tools.
  73. 2. Open Cheat Engine's Lua Engine or script executor.
  74. - Preferred: `File` -> `Execute Script` -> open `MCP_Server/ce_mcp_bridge.lua` -> `Execute`.
  75. - If your Cheat Engine build does not show `File` -> `Execute Script`, use `Table` -> `Show Cheat Table Lua Script`, paste the `dofile(...)` line below, and execute it:
  76. ```lua
  77. dofile([[C:\path\to\cheatengine-mcp-bridge\MCP_Server\ce_mcp_bridge.lua]])
  78. ```
  79. Look for: `[MCP v12.0.0] MCP Server Listening on: CE_MCP_Bridge_v99`
  80. ### 2. Configure MCP Client
  81. Add to your MCP configuration (e.g., `mcp_config.json`):
  82. ```json
  83. {
  84. "servers": {
  85. "cheatengine": {
  86. "command": "python",
  87. "args": ["C:/path/to/MCP_Server/mcp_cheatengine.py"]
  88. }
  89. }
  90. }
  91. ```
  92. Restart the IDE to load the MCP server config.
  93. For Codex, add a TOML server block to `~/.codex/config.toml`:
  94. ```toml
  95. [mcp_servers.cheatengine]
  96. command = "python"
  97. args = ['C:\path\to\cheatengine-mcp-bridge\MCP_Server\mcp_cheatengine.py']
  98. ```
  99. Use single quotes for the Windows path so TOML treats backslashes literally.
  100. #### TCP relay transport
  101. The TCP relay lets `mcp_cheatengine.py` talk to Cheat Engine through a TCP socket instead of opening the Windows named pipe itself. Cheat Engine and the Lua bridge still run on Windows, while the MCP server can run anywhere that can reach the relay: another Windows process, a VM, a container, a Linux host, or a remote machine. This can also be used with WSL without changing the Lua bridge.
  102. 1. On Windows, load `MCP_Server/ce_mcp_bridge.lua` in Cheat Engine as usual.
  103. 2. On Windows, start the relay:
  104. ```powershell
  105. python C:\path\to\cheatengine-mcp-bridge\MCP_Server\ce_tcp_relay.py --host 127.0.0.1 --port 9876
  106. ```
  107. 3. In the environment where the MCP server will run, install the MCP dependency without `pywin32`, then run/configure the MCP server with TCP transport:
  108. ```bash
  109. python3 -m pip install -r MCP_Server/requirements-tcp.txt
  110. ```
  111. ```bash
  112. CE_MCP_TRANSPORT=tcp \
  113. CE_MCP_HOST=127.0.0.1 \
  114. CE_MCP_PORT=9876 \
  115. python3 /path/to/cheatengine-mcp-bridge/MCP_Server/mcp_cheatengine.py
  116. ```
  117. For MCP client configs that support environment variables:
  118. ```json
  119. {
  120. "servers": {
  121. "cheatengine": {
  122. "command": "python3",
  123. "args": ["/path/to/cheatengine-mcp-bridge/MCP_Server/mcp_cheatengine.py"],
  124. "env": {
  125. "CE_MCP_TRANSPORT": "tcp",
  126. "CE_MCP_HOST": "127.0.0.1",
  127. "CE_MCP_PORT": "9876"
  128. }
  129. }
  130. }
  131. }
  132. ```
  133. Set `--host` on the relay and `CE_MCP_HOST` on the MCP server to addresses that match your network setup. Keep the relay bound to trusted interfaces only, because anyone who can reach it can control the Cheat Engine bridge.
  134. ### 3. Verify Connection
  135. Use the `ping` tool to verify connectivity:
  136. ```json
  137. {"success": true, "version": "12.0.0", "message": "CE MCP Bridge Active"}
  138. ```
  139. ### 4. Start Asking Questions
  140. ```
  141. "What process is attached?"
  142. "Read 16 bytes at the base address"
  143. "Disassemble the entry point"
  144. ```
  145. ---
  146. ## ~180 MCP Tools Available
  147. ### Memory
  148. | Tool | Description |
  149. |------|-------------|
  150. | `read_memory`, `read_integer`, `read_string` | Read any data type |
  151. | `read_pointer_chain` | Follow `[[base+0x10]+0x20]` paths |
  152. | `scan_all`, `aob_scan` | Find values and byte patterns |
  153. ### Analysis
  154. | Tool | Description |
  155. |------|-------------|
  156. | `disassemble`, `analyze_function` | Code analysis |
  157. | `dissect_structure` | Auto-detect fields and types |
  158. | `get_rtti_classname` | Identify C++ object types |
  159. | `find_references`, `find_call_references` | Cross-references |
  160. ### Debugging
  161. | Tool | Description |
  162. |------|-------------|
  163. | `set_breakpoint`, `set_data_breakpoint` | Hardware breakpoints |
  164. | `start_dbvm_watch` | Ring -1 invisible tracing |
  165. ### Process Lifecycle
  166. | Tool | Description |
  167. |------|-------------|
  168. | `open_process`, `get_process_list` | Attach to or enumerate running processes |
  169. | `create_process` | Launch a new process under CE's control |
  170. | `pause_process`, `unpause_process` | Suspend / resume target execution |
  171. ### Memory Allocation
  172. | Tool | Description |
  173. |------|-------------|
  174. | `allocate_memory`, `free_memory` | Reserve and release memory in the target |
  175. | `set_memory_protection`, `full_access` | Adjust page protection flags |
  176. ### Code Injection
  177. | Tool | Description |
  178. |------|-------------|
  179. | `inject_dll` | Load a DLL into the target process |
  180. | `execute_code`, `execute_method` | Run shellcode or CE Lua methods remotely |
  181. ### Symbol Management
  182. | Tool | Description |
  183. |------|-------------|
  184. | `register_symbol`, `get_symbol_info` | Create and query named symbols |
  185. | `enable_windows_symbols` | Enable PDB symbol resolution |
  186. ### Assembly / Compilation
  187. | Tool | Description |
  188. |------|-------------|
  189. | `assemble_instruction` | Assemble a single x86/x64 instruction to bytes |
  190. | `compile_c_code` | Compile C source into injected shellcode |
  191. | `generate_api_hook_script` | Generate a CE auto-assembler API hook template |
  192. ### Window / GUI Automation
  193. | Tool | Description |
  194. |------|-------------|
  195. | `find_window` | Locate a window by title or class |
  196. | `send_window_message` | Post `WM_*` messages to a target window |
  197. ### Input Automation
  198. | Tool | Description |
  199. |------|-------------|
  200. | `get_pixel` | Sample a pixel color at screen coordinates |
  201. | `is_key_pressed`, `do_key_press` | Query and simulate keyboard input |
  202. ### Cheat Table
  203. | Tool | Description |
  204. |------|-------------|
  205. | `load_table`, `save_table` | Load / save `.CT` cheat table files |
  206. | `get_address_list` | Enumerate entries in the active cheat table |
  207. ### Kernel Mode (DBK / DBVM)
  208. | Tool | Description |
  209. |------|-------------|
  210. | `dbk_get_cr3` | Read the CR3 register for the target process |
  211. | `read_process_memory_cr3` | Read physical memory via CR3 bypass |
  212. And many more at `AI_Context/MCP_Bridge_Command_Reference.md`
  213. ---
  214. ## Critical Configuration
  215. ### BSOD Prevention
  216. > [!CAUTION]
  217. > **You MUST disable:** Cheat Engine → Settings → Extra → **"Query memory region routines"**
  218. >
  219. > Enabled: Causes `CLOCK_WATCHDOG_TIMEOUT` BSODs due to conflicts with DBVM/Anti-Cheat when scanning protected pages.
  220. ---
  221. ## Troubleshooting
  222. ### Cheat Engine says "too many local variables"
  223. Load the bridge from disk with `dofile(...)` instead of pasting the full script into a cheat table script. The bridge also declares command handlers as global functions intentionally; this avoids Cheat Engine's Lua chunk limit of 200 local variables when the complete bridge is compiled at once.
  224. ### MCP client cannot connect
  225. Check these in order:
  226. 1. Cheat Engine is open and shows `MCP Server Listening on: CE_MCP_Bridge_v99`.
  227. 2. The MCP client was restarted after adding the server config.
  228. 3. The configured `mcp_cheatengine.py` path exists.
  229. 4. `pip install -r MCP_Server/requirements.txt` has installed both `mcp` and `pywin32`.
  230. 5. Run the MCP `ping` tool. A successful connection returns `success: true` and the bridge version. `process_id: 0` is normal until Cheat Engine is attached to a target process.
  231. ---
  232. ## Environment Variables
  233. | Variable | Default | Purpose |
  234. |----------|---------|---------|
  235. | `CE_MCP_TIMEOUT` | `30` | Timeout (seconds) for each MCP tool call. |
  236. | `CE_MCP_ALLOW_SHELL` | *unset* | Set to `1` to enable `run_command` / `shell_execute` tools. **Arbitrary code execution risk** — leave unset by default. |
  237. ---
  238. ## Example Workflows
  239. **Finding a value:**
  240. ```
  241. You: "Scan for gold: 15000" → AI finds 47 results
  242. You: "Gold changed to 15100" → AI filters to 3 addresses
  243. You: "What writes to the first one?" → AI sets hardware BP
  244. You: "Disassemble that function" → Full AddGold logic revealed
  245. ```
  246. **Understanding a structure:**
  247. ```
  248. You: "What's at [[game.exe+0x1234]+0x10]?"
  249. AI: "RTTI: CPlayerInventory"
  250. AI: "0x00=vtable, 0x08=itemCount(int), 0x10=itemArray(ptr)..."
  251. ```
  252. ---
  253. ## Project Structure
  254. ```
  255. CLAUDE.md # Claude Code agent guidance (this repo)
  256. README.md # User-facing documentation
  257. MCP_Server/
  258. ├── mcp_cheatengine.py # Python MCP Server (FastMCP)
  259. ├── ce_mcp_bridge.lua # Cheat Engine Lua Bridge
  260. └── test_mcp.py # Test Suite
  261. AI_Context/
  262. ├── BATCH_WORKER_BRIEFING.md # Parallel-worker task specifications (v12 overhaul)
  263. ├── MCP_Bridge_Command_Reference.md # MCP Commands reference
  264. ├── CE_LUA_Documentation.md # Full CheatEngine 7.6 official documentation
  265. └── AI_Guide_MCP_Server_Implementation.md # Full technical documentation for AI agent
  266. ```
  267. ---
  268. ## Testing
  269. Running the test:
  270. ```bash
  271. python MCP_Server/test_mcp.py
  272. ```
  273. Expected output:
  274. ```
  275. ✅ Memory Reading: 6/6 tests passed
  276. ✅ Process Info: 4/4 tests passed
  277. ✅ Code Analysis: 8/8 tests passed
  278. ✅ Breakpoints: 4/4 tests passed
  279. ✅ DBVM Functions: 3/3 tests passed
  280. ✅ Utility Commands: 11/11 tests passed
  281. ⏭️ Skipped: 1 test (generate_signature)
  282. ────────────────────────────────────
  283. Total: 36/37 PASSED (100% success)
  284. ```
  285. ---
  286. ## The Bottom Line
  287. You no longer need to be an expert. Just ask the right questions.
  288. ⚠️ EDUCATIONAL DISCLAIMER
  289. This code is for educational and research purposes only. It's created to show the capabilities of the Model Context Protocol (MCP) and LLM-based debugging. I do not condone the use of these tools for malicious hacking, cheating in multiplayer games, or violating Terms of Service. This is a demonstration of software engineering automation.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.