Content
**English** | [中文](docs/README_zh.md) | [日本語](docs/README_ja.md) | [한국어](docs/README_ko.md) | [Русский](docs/README_ru.md) | [العربية](docs/README_ar.md)
# Cheat Engine MCP Bridge
**Let AI agents read, write, scan, and debug any process through Cheat Engine.**
[](#) [](https://python.org) [](LICENSE) [](#)
120 MCP tools for memory analysis, reverse engineering, debugging, and game modding -- all driven by natural language through any MCP-compatible AI agent (Claude, Cursor, Copilot, etc).
> [!NOTE]
> Thanks everyone for the stars, much appreciated! <3
---
## Quick Start
### Prerequisites
- **Windows** (required -- uses Named Pipes)
- **Cheat Engine 7.x** installed
- **Python 3.10+** with pip
### Step 1: Install Python Dependencies
```bash
pip install mcp pywin32
```
### Step 2: Load the Bridge in Cheat Engine
**Option A — Manual (per session):**
1. Open Cheat Engine
2. **File > Execute Script** > select `lua/ce_mcp_bridge.lua` > **Execute**
**Option B — Auto-load (recommended):**
Copy `lua/ce_mcp_bridge.lua` into Cheat Engine's `autorun` directory so it loads every time CE starts:
```
C:\Program Files\Cheat Engine 7.x\autorun\ce_mcp_bridge.lua
```
After loading, confirm output: `[MCP v11.4.0] Server started on CE_MCP_Bridge_v99`, then attach to your target process as usual.
### Step 3: Configure Your AI Client
Add the following to your MCP client config (replace `C:/path/to/cheat-engine-mcp` with the actual clone path):
```json
{
"mcpServers": {
"cheatengine": {
"command": "python",
"args": ["-m", "ce_mcp"],
"env": {
"PYTHONPATH": "C:/path/to/cheat-engine-mcp"
}
}
}
}
```
Config file locations:
- **Cursor**: `~/.cursor/mcp.json`
- **Antigravity**: `~/.antigravity/mcp.json`
- **Claude Desktop**: `%APPDATA%\Claude\claude_desktop_config.json`
### Step 4: Verify
Ask your AI agent: *"Ping the Cheat Engine bridge"*
Expected: `{"success": true, "version": "11.4.0", "message": "CE MCP Bridge Active"}`
---
## What Can It Do?
| Category | Tools | Examples |
|----------|-------|---------|
| **Memory** | read/write integers, floats, strings, raw bytes, pointer chains | `read_pointer_chain("game.exe+0x1234", [0x10, 0x20, 0x8])` |
| **Scanning** | value scan, AOB pattern scan, string search, next scan | `scan_all("1000")` then `next_scan("999")` |
| **Analysis** | disassemble, analyze functions, find references, RTTI, structures | `disassemble("game.exe+0x5000", 20)` |
| **Debugging** | hardware/software breakpoints, find what writes/accesses, stepping | `find_what_writes("0x12345678", timeout=5)` |
| **Cheat Table** | create/modify/delete entries, scripts, hotkeys, save/load .CT files | `create_table_entry("Infinite HP", address="game.exe+0x1234")` |
| **DBVM** | invisible Ring -1 tracing, code cloaking, register modification | `start_dbvm_watch("0x12345678", mode="w")` |
| **Scripting** | execute Lua, Auto Assembler, generate injection templates | `generate_aob_injection("game.exe+0x5000")` |
| **Process** | attach, enumerate modules/threads, resolve symbols | `open_process("game.exe")` |
Full API reference: [`ce_mcp/ai_docs/command_reference.md`](ce_mcp/ai_docs/command_reference.md)
---
## Architecture
```mermaid
flowchart LR
AI["AI Agent\n(Claude / Cursor / Copilot)"]
PY["Python MCP Server\npython -m ce_mcp"]
PIPE["Named Pipe\nCE_MCP_Bridge_v99"]
LUA["Lua Bridge\nce_mcp_bridge.lua"]
TARGET["Target Process"]
AI -->|"MCP (JSON-RPC / stdio)"| PY
PY <-->|"Binary-framed JSON-RPC"| PIPE
PIPE <-->|"Worker Thread"| LUA
LUA -->|"CE API calls\n(main thread sync)"| TARGET
```
- **Python side** (`ce_mcp/`): Translates MCP tool calls into named-pipe commands. Stateless -- all state lives in CE.
- **Lua side** (`lua/ce_mcp_bridge.lua`): Runs inside CE. Worker thread handles pipe I/O; commands execute on the main thread via `thread.synchronize` so all CE APIs are safe to call.
- **Protocol**: 4-byte little-endian length header + UTF-8 JSON-RPC 2.0 body.
---
## Example Workflows
**Find and freeze a value:**
```
You: "Scan for gold: 15000" → AI calls scan_all("15000")
You: "Gold changed to 15100" → AI calls next_scan("15100"), finds 3 addresses
You: "What writes to the first one?" → AI calls find_what_writes(addr, timeout=5)
You: "Generate an AOB injection for it" → AI calls generate_aob_injection(addr)
```
**Reverse-engineer a structure:**
```
You: "What's at [[game.exe+0x1234]+0x10]?"
AI: reads pointer chain, identifies RTTI: CPlayerInventory
AI: "0x00=vtable, 0x08=itemCount(int:24), 0x10=itemArray(ptr)..."
```
---
## Critical Configuration
> [!CAUTION]
> **You MUST disable:** Cheat Engine > Settings > Extra > **"Query memory region routines"**
>
> Leaving it enabled causes `CLOCK_WATCHDOG_TIMEOUT` BSODs when DBVM or anti-cheat conflicts with memory region scanning.
---
## Project Structure
```
ce_mcp/ # Python MCP Server package
├── __main__.py # Entry point (python -m ce_mcp)
├── server.py # FastMCP instance
├── client.py # Named-pipe bridge client
├── protocol.py # Shared constants
├── _compat.py # Windows stdio patch
├── tools/ # 120 MCP tools
│ ├── _helpers.py # Shared tool utilities
│ ├── process.py # Process, modules, version
│ ├── memory.py # Read / write / allocate
│ ├── scanning.py # Value & pattern scanning
│ ├── analysis.py # Disassembly, structures, symbols
│ ├── debugger.py # Breakpoints, debugger, threads
│ ├── cheat_table.py # Cheat table operations
│ ├── dbvm.py # DBVM hypervisor (Ring -1)
│ └── scripting.py # Lua eval, AA, injection gen
└── ai_docs/ # AI knowledge base
├── command_reference.md # Full API reference (all 120 tools)
├── tool_guide.md # AI agent usage guide
└── ce_lua_api.md # CE 7.6 Lua API reference
lua/ce_mcp_bridge.lua # Cheat Engine Lua bridge
tests/ # Test suite
├── test_bridge.py # Low-level pipe protocol tests
├── test_lang_display.py # Multi-language dialog tests
└── test_safe_tools.py # Comprehensive safe-tools tests
docs/ # Human-facing translations
├── README_zh.md # 中文
├── README_ja.md # 日本語
├── README_ko.md # 한국어
├── README_ru.md # Русский
└── README_ar.md # العربية
requirements.txt # pip dependencies
```
---
## Acknowledgements
Core code derived from [cheatengine-mcp-bridge](https://github.com/miscusi-peek/cheatengine-mcp-bridge) by miscusi-peek.
---
## Disclaimer
This project is for **educational and research purposes only**. It demonstrates the capabilities of the Model Context Protocol (MCP) for software analysis automation. Do not use it for malicious hacking, cheating in multiplayer games, or violating Terms of Service.
