🧠 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:

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

Related MCP server: PCILeech MCP Server

🛠️ Capabilities

40+ tools covering effectively the whole manual workflow:

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:

🔒 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.