🧠 ce-mcp — Cheat Engine MCP Server

Give an AI agent full, programmatic control of Cheat Engine through the Model Context Protocol.

ce-mcp lets a model like Claude attach to a running process, scan and edit memory, build cheat tables, resolve pointer chains, disassemble/assemble code, run Auto Assembler scripts, and inspect Unity/Mono games — the same workflow a human reverse-engineer follows in the Cheat Engine UI, exposed as clean MCP tools.

"Attach to the game, find my health value, then freeze it."
        │
   ┌────▼─────────┐    MCP/stdio    ┌──────────────┐   HTTP/JSON   ┌──────────────┐
   │   AI agent   │ ───────────────▶│  ce-mcp       │ ─────────────▶│ Cheat Engine │
   │ (Claude etc) │ ◀───────────────│ (Python,      │ ◀─────────────│ Lua bridge   │
   └──────────────┘                 │  FastMCP)     │  37712        │ (in-process) │
                                    └──────────────┘                └──────────────┘

---

✨ Why this design

Cheat Engine has no external API — its automation surface lives entirely in its embedded Lua engine. ce-mcp bridges that gap with two cooperating halves:

Half	Lives in	Job
Lua bridge (lua/ce_mcp_bridge.lua)	Inside Cheat Engine	Tiny loopback HTTP/JSON server that calls CE's Lua API directly — scanning, reading/writing, AA, debugger, Mono. Ships its own hand-written JSON parser (no external deps).
MCP server (src/ce_mcp/)	Python process	Speaks MCP over stdio to the agent, translates each tool call into an HTTP request to the bridge. Built on the official mcp SDK (FastMCP).

This keeps the agent-facing contract clean and typed, while all the CE-specific magic stays where it has to be — inside Cheat Engine.

---

🛠️ Capabilities

40+ tools covering effectively the whole manual workflow:

Group	Tools
Process	process_list, process_attach, process_detach, process_current, process_modules, process_regions
Memory	memory_read, memory_read_batch, memory_write, memory_dump, memory_alloc, memory_free
Scanning	scan_first, scan_next, scan_results, scan_reset, scan_aob
Cheat table	table_list, table_add, table_remove, table_set_value, table_freeze, table_enable, table_hotkey, table_save, table_load, table_clear
Pointers	pointer_resolve, pointer_scan
Code	disassemble, assemble, auto_assemble
Debugger	find_what_writes, find_what_accesses, breakpoint
Mono/Unity	mono_init, mono_classes
Misc	speedhack, lua_execute (raw Lua escape hatch), ce_status, ce_version, ce_routes

Every scan type Cheat Engine supports is available: exact, bigger, smaller, between, unknown, changed, unchanged, increased, decreased, increasedby, decreasedby. Every value type too: byte … qword, float, double, string (incl. UTF-16), and AOB byte arrays with wildcards.

---

🚀 Quick start

1. Requirements

• Windows with Cheat Engine 7.x installed
• Python 3.10+

2. Install the Python server

git clone https://github.com/imrx44/mcp.git
cd mcp
pip install -e .
# or, without packaging:  pip install -r requirements.txt

3. Start the in-CE bridge

1. Open Cheat Engine.
2. Table ▸ Cheat Table Lua Script (Ctrl+Alt+L).
3. Paste the contents of lua/ce_mcp_bridge.lua and click Execute.
4. The CE console prints: [CE-MCP] listening on http://127.0.0.1:37712.

💡 To auto-start it every time, drop the file into Cheat Engine's autorun/ folder.

4. Wire it into your MCP client

Add the block from examples/claude_desktop_config.json to your Claude Desktop config (or any MCP client), pointing PYTHONPATH at this repo's src/. Restart the client and the cheat-engine tools appear.

5. Verify

Ask the agent: "Run ce_status." — you should get the Cheat Engine version back.

---

🎮 Example: freeze your health (end to end)

A natural-language session the agent can now carry out by itself:

1. process_list  filter="game"            → find the pid
2. process_attach process="game.exe"
3. scan_first  value=100  value_type="4byte"  scan_type="exact"
   ... take damage in-game ...
4. scan_next   value=92  scan_type="exact"
   ... repeat until one result remains ...
5. scan_results                            → 0x1F3A4C20
6. table_add   address="0x1F3A4C20"  description="Health"  type="4byte"
7. table_freeze id=<id>                    → health locked

And a code-injection ("godmode") cheat via Auto Assembler:

auto_assemble(script="""
[ENABLE]
aobscanmodule(hpHook,game.exe,29 87 ?? ?? ?? ??)   // sub [edi+offset],eax
alloc(newmem,128,hpHook)
label(ret)
newmem:
  // skip the subtract → take no damage
  jmp ret
hpHook:
  jmp newmem
  nop 2
ret:
[DISABLE]
hpHook:
  db 29 87 ?? ?? ?? ??
dealloc(newmem)
""")

---

⚙️ Configuration

The Python server reads these environment variables:

Variable	Default	Meaning
CE_MCP_HOST	127.0.0.1	Bridge host
CE_MCP_PORT	37712	Bridge port (must match the Lua file)
CE_MCP_TIMEOUT	60	HTTP timeout (s) — raise for long scans

---

🔒 Security notes

• The bridge binds to loopback only and has no authentication — anything that can reach localhost:37712 can drive Cheat Engine. Don't expose the port.
• This is a debugging / reverse-engineering tool. Use it on software you own or are authorised to analyse, and respect the terms of service of online games.

---

🧩 Architecture details

• No external Lua dependencies. The bridge implements its own recursive-descent JSON encoder/decoder, so it runs on a stock Cheat Engine install.
• Non-blocking server. The HTTP accept loop runs on a CE timer, so it never freezes the Cheat Engine UI.
• Stateful scan session. scan_first creates a CE MemScan/FoundList that later scan_next/scan_results/scan_reset calls operate on — mirroring the UI.
• Clean error contract. Every response is { ok, data | error }; the Python client raises a typed BridgeError that tools surface as a readable message.

See docs/TOOLS.md for the full per-tool reference.

---

📁 Project layout

MCP/
├── lua/
│   └── ce_mcp_bridge.lua        # In-Cheat-Engine HTTP/JSON bridge
├── src/ce_mcp/
│   ├── server.py                # FastMCP server + all tool definitions
│   ├── client.py                # Async HTTP client for the bridge
│   ├── __main__.py              # python -m ce_mcp
│   └── __init__.py
├── examples/
│   └── claude_desktop_config.json
├── docs/
│   └── TOOLS.md                 # Full tool reference
├── pyproject.toml
├── requirements.txt
└── README.md

---

📜 License

MIT — see LICENSE.

Not affiliated with Cheat Engine or its author. "Cheat Engine" is the property of its respective owners.