内容
# 🎮 cheat-engine-mcp
[](https://github.com/gede-cahya/cheat-engine-mcp/actions/workflows/ci.yml)
[](https://github.com/gede-cahya/cheat-engine-mcp/releases)
[](LICENSE)
[](https://github.com/gede-cahya)
**AI-powered game memory scanner and reverse engineering toolkit** — an MCP (Model Context Protocol) server that gives AI coding assistants direct access to memory scanning, process memory editing, and IL2CPP reverse engineering tools across **Linux & Windows**.
> Turn your AI assistant into a game hacking partner. Scan memory, freeze values, search IL2CPP metadata, and modify game values — all through natural language.
---
## ✨ Features
| Category | Tools | Description | Supported OS |
|---|---|---|---|
| 🔍 **Memory Scanning** | `scanmem_scan_*`, `session_*` | Exact, range, type-based, increased/decreased/changed value scanning | **Linux & Windows** |
| 🧱 **Memory Alloc & Protect** | `memory_allocate`, `memory_protect`, `memory_free` | Allocate virtual memory (`VirtualAllocEx` / `mmap`), set page protection flags (`VirtualProtectEx` / `mprotect`), and free stubs | **Linux & Windows** |
| ✏️ **Memory Writing** | `scanmem_write_*`, `memory_write_bytes` (up to 64KB), `scanmem_freeze_*` | Safe guarded writes with preview, dry-run, confirmation, hex patching, and persistent freeze | **Linux & Windows** |
| 📖 **Memory Reading** | `memory_read_*` | Read bytes, ints, floats, and strings from process memory | **Linux & Windows** |
| 🧬 **IL2CPP Reverse** | `il2cpp_*` | Search classes, methods, fields, strings, and RVA in Unity IL2CPP dumps | **Linux & Windows** |
| 🔄 **IL2CPP Automation** | `il2cpp_run_dumper`, `il2cpp_scan_taskbarhero_offsets` | Automated dumper execution & deterministic heuristic offset recovery across game updates | **Linux & Windows** |
| 📊 **Cheat Tables** | `table_*` | Save/load/resolve/validate cheat entries with module+RVA tracking | **Linux & Windows** |
| 📋 **Reports** | `reverse_report_*` | Create and manage local reverse engineering reports per game | **Linux & Windows** |
| 🎯 **Process Utils** | `process_*`, `rva_*` | Process search, module listing, RVA/address conversion, memory maps | **Linux & Windows** |
| 🔬 **GDB Hooks** | `gdb_hook_*`, `gdb_probe_*` | Dynamic function hooking, breakpoint probes, disassembly preview | Linux only |
**78 MCP tools** in total — all accessible via natural language through any MCP-compatible AI assistant.
---
## 🚀 Quick Start
### 1. Install Dependencies
#### Linux
```bash
# Arch Linux
sudo pacman -S scanmem gdb rust
# Debian / Ubuntu
sudo apt update && sudo apt install -y scanmem gdb cargo
```
#### Windows
No external dependencies (`scanmem` or GDB) required! The memory engine runs natively via Win32 API (`kernel32.dll`).
Install Rust if building from source:
```powershell
winget install Rustlang.Rustup
```
---
### 2. Install on Linux
```bash
git clone https://github.com/gede-cahya/cheat-engine-mcp.git
cd cheat-engine-mcp
./install.sh
```
This builds the release binary and installs it to:
```bash
~/.local/bin/cheat-engine-mcp
```
Add this MCP config to your client:
```json
{
"mcpServers": {
"cheat-engine-mcp": {
"command": "/home/YOUR_USER/.local/bin/cheat-engine-mcp"
}
}
}
```
---
### 3. Install on Windows
Build the MCP server natively (or run `install-antigravity.ps1`):
```powershell
git clone https://github.com/gede-cahya/cheat-engine-mcp.git
cd cheat-engine-mcp
cargo build --release
```
Copy the binary to a stable location:
```powershell
New-Item -ItemType Directory -Force C:\Tools | Out-Null
Copy-Item .\target\release\cheat-engine-mcp.exe C:\Tools\cheat-engine-mcp.exe
```
Check it:
```powershell
C:\Tools\cheat-engine-mcp.exe --help
```
Add this MCP config to your client:
```json
{
"mcpServers": {
"cheat-engine-mcp": {
"command": "C:\\Tools\\cheat-engine-mcp.exe"
}
}
}
```
Or run the automated setup script for Antigravity:
```powershell
.\install-antigravity.ps1
```
### 4. Connect to Your AI Assistant
Choose your AI assistant and follow [Install cheat-engine-mcp ke MCP Client](docs/INSTALL_MCP_CLIENTS.md).
| AI Assistant | Config | Skill support |
|---|---|---|
| **Google Antigravity** | `~/.gemini/config/settings.json` or `%USERPROFILE%\.gemini\config\settings.json` | Copy `SKILL.md` into Antigravity/Gemini skills folder if enabled |
| **Claude Code** | `.claude/settings.json` per repo | `.claude/skills/cheat-engine-mcp/SKILL.md` |
| **Claude Desktop** | `claude_desktop_config.json` | Use project instructions / prompt installer |
| **Cursor / Windsurf / Generic MCP** | Client MCP config file | Use the prompt installer or custom rules |
Need an agent to install it for you? Copy [docs/SKILL_INSTALL_PROMPT.md](docs/SKILL_INSTALL_PROMPT.md) into Antigravity, Claude Code, or another coding agent.
---
## 🔧 MCP Client Configuration
All MCP-compatible clients use the same server binary. The only difference is where the config file lives.
### Config File Locations
| Client | Linux | macOS | Windows |
|---|---|---|---|
| **Antigravity** | `~/.gemini/config/settings.json` | `~/.gemini/config/settings.json` | `%USERPROFILE%\.gemini\config\settings.json` |
| **Claude Code** | `.claude/settings.json` (per-repo) | Same | Same |
| **Claude Desktop** | `~/.config/Claude/claude_desktop_config.json` | `~/Library/Application Support/Claude/claude_desktop_config.json` | `%APPDATA%\Claude\claude_desktop_config.json` |
| **Cursor** | `.cursor/mcp.json` (per-project) | Same | Same |
---
## 🧠 Skill / Plugin Installation
For the best experience, install the **skill definition** so your AI assistant knows *how* to use the tools effectively.
### Google Antigravity
```bash
mkdir -p ~/.gemini/config/skills/cheat-engine-mcp
cp .claude/skills/cheat-engine-mcp/SKILL.md ~/.gemini/config/skills/cheat-engine-mcp/SKILL.md
```
### Claude Code
```bash
mkdir -p YOUR_REPO/.claude/skills
cp -r .claude/skills/cheat-engine-mcp/ YOUR_REPO/.claude/skills/cheat-engine-mcp/
cp CLAUDE.md YOUR_REPO/CLAUDE.md
```
---
## 🎯 Usage Examples
Once configured, just talk to your AI assistant naturally:
### Find and modify a game value
```
"Scan game TaskbarHero for health value 100, then set it to 999"
```
The AI will:
1. `process_search` → find the game PID
2. `session_create` → create a scan session
3. `scanmem_scan_exact` → scan for value 100
4. Refine with `scanmem_scan_decreased` / `scanmem_scan_unchanged`
5. `scanmem_preview_write` → preview the write
6. `scanmem_write_selected` → apply with safety guards
### Reverse engineer a Unity/IL2CPP game
```
"Search for Hero class methods in TaskbarHero's IL2CPP dump"
```
The AI will:
1. `workspace_set_active` → set game workspace
2. `il2cpp_class_search` → find Hero class
3. `il2cpp_method_search` → find relevant methods
4. `il2cpp_field_search` → find class fields and offsets
5. `il2cpp_find_by_rva` → map RVA addresses
### Automate IL2CPP Dump & Offset Recovery After Game Update
```
"Game Taskbar Heroes habis update, tolong dump dan scan offset terbarunya untuk godmode dan damage"
```
The AI will:
1. `process_search` → find `TaskbarHero.exe` live PID
2. `il2cpp_run_dumper` → automatically run Il2CppDumper from PID
3. `il2cpp_scan_taskbarhero_offsets` → heuristically match anchors on `dump.cs`:
- Base health & Damage RVA (`pj.gsi`)
- Hero Receiver Godmode RVA (`pf.gsi`)
- Stat multiplier RVA (`zo.haz`)
- AoE radius & hitbox RVA (`bec.nax`)
4. Compute Runtime Addresses (`Base + RVA`) and output Markdown comparison table
5. `memory_write_bytes` → apply godmode byte patches with confirmation
### Hook a game function with GDB
```
"Hook the damage function at RVA 0x958ADC in GameAssembly.dll and multiply damage by 1000"
```
The AI will:
1. `rva_disassemble_preview` → inspect the function
2. `gdb_hook_preview` → preview the hook script
3. `gdb_hook_start` → attach and hook (with confirmation)
4. Monitor via log output
---
## 🛠️ Tool Reference
### Process & Memory
| Tool | Description |
|---|---|
| `process_search` | Search running processes by name |
| `process_info` | Get detailed process information |
| `process_suggest_target` | AI-friendly target suggestion |
| `process_list_modules` | List loaded modules/DLLs |
| `process_read_maps` | Read `/proc/PID/maps` |
| `process_module_base` | Get module base address |
| `rva_to_address` | Convert RVA to absolute address |
| `address_to_rva` | Convert absolute address to RVA |
| `memory_read_bytes` | Read raw bytes from memory |
| `memory_read_int` | Read integer value |
| `memory_read_float` | Read float value |
| `memory_read_string` | Read string from memory |
### Scanning
| Tool | Description |
|---|---|
| `session_create` | Create scan session for a PID |
| `session_status` | Check session state |
| `session_close` | Close session and cleanup |
| `scanmem_scan_exact` | Scan for exact value |
| `scanmem_scan_increased` | Filter: value increased |
| `scanmem_scan_decreased` | Filter: value decreased |
| `scanmem_scan_changed` | Filter: value changed |
| `scanmem_scan_unchanged` | Filter: value unchanged |
| `scanmem_scan_unknown` | Initial unknown value scan |
| `scanmem_scan_range` | Scan value range |
| `scanmem_scan_by_type` | Typed scan (int32/float/string/etc.) |
### Writing & Allocation
| Tool | Description |
|---|---|
| `memory_allocate` | Allocate virtual memory (`VirtualAllocEx` on Windows, `mmap` on Linux) with `rwx`, `rw`, `rx`, or `r` permissions |
| `memory_protect` | Modify memory page protection flags (`VirtualProtectEx` on Windows, `mprotect` on Linux) |
| `memory_free` | Free or decommit virtual memory (`VirtualFreeEx` on Windows, `munmap` on Linux) |
| `memory_write_bytes` | Write bounded raw hex bytes (up to 64KB, e.g. code cave payloads, detour stubs) directly to memory / RVA |
| `scanmem_preview_write` | Preview write operation (safe) |
| `scanmem_write_selected` | Write to matched addresses |
| `scanmem_freeze_value` | Freeze value (one-shot or persistent) |
| `scanmem_unfreeze_value` | Stop freezing |
### GDB Hooks
| Tool | Description |
|---|---|
| `gdb_hook_preview` | Preview single hook script |
| `gdb_hook_start` | Start single GDB hook |
| `gdb_hook_stop` | Stop hook and detach |
| `gdb_hook_group_preview` | Preview multi-breakpoint hook |
| `gdb_hook_group_start` | Start hook group |
| `gdb_hook_group_stop` | Stop hook group |
| `gdb_probe_preview` | Preview read-only probe |
| `gdb_probe_start` | Start probe (auto-stops after N hits) |
| `gdb_probe_stop` | Stop probe |
| `rva_disassemble_preview` | Disassemble at RVA |
| `gdb_disassemble_address` | Disassemble at absolute address |
| `gdb_breakpoint_probe_preview` | Preview breakpoint probe |
### IL2CPP Reverse Engineering & Automation
| Tool | Description |
|---|---|
| `il2cpp_run_dumper` | Automatically run Il2CppDumper from live PID or GameAssembly.dll path |
| `il2cpp_scan_taskbarhero_offsets` | Heuristic anchor scan on dump.cs to discover Godmode, Instakill, and AoE RVAs |
| `il2cpp_artifacts_status` | Check dump.cs availability |
| `il2cpp_class_search` | Search classes by name |
| `il2cpp_method_search` | Search methods by name |
| `il2cpp_field_search` | Search fields by name |
| `il2cpp_string_search` | Search string literals |
| `il2cpp_script_search` | Search MonoBehaviour scripts |
| `il2cpp_method_detail` | Get method details |
| `il2cpp_find_by_rva` | Find method by RVA |
| `il2cpp_related_methods` | Find related methods |
### Workspace & Reports
| Tool | Description |
|---|---|
| `workspace_list` | List all game workspaces |
| `workspace_status` | Current workspace status |
| `workspace_set_active` | Set active workspace |
| `workspace_clear_active` | Clear active workspace |
| `reverse_report_create` | Create reverse report |
| `reverse_report_add_finding` | Add finding to report |
| `reverse_report_list` | List reports for a game |
### Cheat Tables
| Tool | Description |
|---|---|
| `table_create` | Create new cheat table |
| `table_add_entry` | Add entry to table |
| `table_list_entries` | List table entries |
| `table_resolve_entries` | Resolve RVAs to addresses |
| `table_validate_entries` | Validate entries against live process |
| `table_load` | Load table from file |
| `table_save` | Save table to file |
---
## 🔒 Safety Design
This tool is built with **defense-in-depth safety**:
1. **Preview First** — All destructive operations have a preview/dry-run mode
2. **Explicit Confirmation** — Writes require `confirm_write: true`, hooks require `confirm_hook: true`
3. **Write Limits** — `max_writes` caps the number of addresses modified
4. **Dry Run** — `dry_run: true` simulates without touching memory
5. **GDB Command Whitelist** — Only `set`, `printf`, `if/else/end` allowed in hook scripts
6. **Session Timeout** — Scan sessions auto-expire after 30 minutes
7. **Live PID Check** — Validates process is alive before any operation
---
## 🏗️ Building from Source
### Linux
```bash
git clone https://github.com/gede-cahya/cheat-engine-mcp.git
cd cheat-engine-mcp
cargo build --release
# Binary: ./target/release/cheat-engine-mcp
```
### Windows
```powershell
git clone https://github.com/gede-cahya/cheat-engine-mcp.git
cd cheat-engine-mcp
cargo build --release
# Binary: .\target\release\cheat-engine-mcp.exe
```
### Install to PATH
```bash
./install.sh
# Installs to ~/.local/bin/cheat-engine-mcp
# Custom prefix:
PREFIX=/usr/local sudo -E ./install.sh
```
---
## 🧪 Testing
```bash
cargo fmt --check
cargo test
cargo check
cargo build --release
(cd examples/dummy-target && cargo check)
```
### Manual MCP Test
```bash
# Initialize
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | cargo run -q
# List tools
printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | cargo run -q
# Ping
printf '%s\n' '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ping","arguments":{}}}' | cargo run -q
```
### Dummy Target
```bash
# Terminal 1: Start dummy target
cd examples/dummy-target && cargo run
# Terminal 2: Scan with PID from terminal 1
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"scanmem_scan_exact","arguments":{"pid":PID,"value":"100"}}}' | cargo run -q
```
---
## 🐧 Linux Troubleshooting
### ptrace Permission
```bash
# Check current setting
cat /proc/sys/kernel/yama/ptrace_scope
# Allow ptrace (for development)
sudo sysctl kernel.yama.ptrace_scope=0
# Restore default (more secure)
sudo sysctl kernel.yama.ptrace_scope=1
```
### Common Issues
| Problem | Solution |
|---|---|
| `scanmem` not found | Install: `sudo apt install scanmem` or `sudo pacman -S scanmem` |
| `gdb` not found | Install: `sudo apt install gdb` or `sudo pacman -S gdb` |
| Permission denied | Run MCP and target as same user; check ptrace_scope |
| PID not found | Ensure target process is running; check with `pgrep` |
| Too many matches | Use refine scans (increased/decreased/unchanged) |
---
## 📁 Project Structure
```
cheat-engine-mcp/
├── src/
│ ├── main.rs # MCP server (78 tools, JSON-RPC router)
│ ├── native_scan.rs # Pure cross-platform memory buffer scanner
│ ├── windows.rs # Win32 API native process memory backend
│ └── il2cpp_heuristic.rs # Heuristic anchor offset recovery engine
├── Cargo.toml # Rust project config
├── install.sh # Linux install script
├── install-antigravity.sh # Antigravity one-click installer
├── install-antigravity.ps1 # Antigravity Windows installer
├── install-claude-code.sh # Claude Code one-click installer
├── install-claude-code.ps1 # Claude Code Windows installer
├── skills/
│ └── antigravity/ # Antigravity skill definition
│ ├── SKILL.md
│ └── AGENTS.md
├── .claude/
│ └── skills/
│ └── cheat-engine-mcp/ # Claude Code skill definition
│ └── SKILL.md
├── docs/
│ ├── SETUP_ANTIGRAVITY.md
│ ├── SETUP_CLAUDE_CODE.md
│ ├── SETUP_CLAUDE_DESKTOP.md
│ ├── SETUP_CURSOR.md
│ ├── SETUP_GENERIC.md
│ ├── REVERSE_OFFSETS.md
│ ├── RULES_INSTALL.md
│ ├── RELEASE.md
│ └── *.example.json
├── examples/
│ └── dummy-target/ # Test target for scanning
├── reverse/ # Local reverse artifacts (gitignored)
├── .cheat-tables/ # Local cheat tables (gitignored)
├── .github/workflows/ # CI + Release automation
├── CLAUDE.md # Claude Code project rules
├── README.md
├── ROADMAP.md
└── LICENSE
```
---
## 📜 License
[MIT License](LICENSE) © gede-cahya
---
## 🤝 Contributing
1. Fork the repo
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Run tests (`cargo fmt --check && cargo test && cargo check`)
4. Commit your changes (`git commit -m 'Add amazing feature'`)
5. Push to the branch (`git push origin feature/amazing-feature`)
6. Open a Pull Request
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器