miscusi-peek/cheatengine-mcp-bridgeConecta tus agentes de IA favoritos directamente a Cheat Engine mediante MCP. Automatiza la ingeniería inversa, el escaneo de punteros y el análisis de memoria usando lenguaje natural.
[Demostración](https://github.com/user-attachments/assets/a184a006-f569-4b55-858a-ed80a7139035)
# Cheat Engine MCP Bridge
**Permite que centros de datos de IA multimillonarios analicen la memoria del programa por ti.**
Crea mods, trainers, auditorías de seguridad, bots de juegos, acelera la ingeniería inversa, o haz cualquier otra cosa con cualquier programa y juego en una fracción del tiempo.
[](#) [](https://python.org)
> [!NOTE]
> ¡Gracias a todos por las estrellas, muy apreciado! <3
>
> Especialmente un gran agradecimiento a todos los colaboradores!!
>
> [@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)
---
## El Problema
Estás mirando gigabytes de memoria. Millones de direcciones. Miles de funciones. Encontrar *ese puntero*, *esa estructura* lleva **días o semanas** de trabajo manual.
**¿Qué tal si pudieras simplemente preguntar?**
> *"Encuentra el hook del descifrador de paquetes."*
> *"Encuentra el OPcode de las coordenadas del personaje."*
> *"Encuentra el OPcode de los valores de salud."*
> *"Encuentra el patrón AOB único para hacer que mi trainer sea confiable después de las actualizaciones del juego."*
**Eso es exactamente lo que esto hace.**
_- Deja de hacer clic en volcados hexadecimales y comienza a tener conversaciones con la memoria._
---
## Lo Que Obtienes:
| Antes (Manual) | Después (Agente IA + MCP) |
|-----------------|---------------------|
| Día 1: Encontrar dirección del paquete | Minuto 1: "Encontrar hook de descifrado de paquetes RX" |
| Día 2: Rastrear qué escribe en ella | Minuto 3: "Generar firma AOB única para hacerla persistente a actualizaciones" |
| Día 3: Encontrar hook RX | Minuto 6: "Encontrar OPcodes de movimiento" |
| Día 4: Documentar estructura | Minuto 10: "Crear intérprete de Python de hex a texto plano" |
| Día 5: Actualizaciones del juego, empezar de nuevo | **Hecho.** |
**Tu IA ahora puede:**
- Leer cualquier memoria instantáneamente (enteros, flotantes, cadenas, punteros)
- Seguir cadenas de punteros: `[[base+0x10]+0x20]+0x8` → resuelto en ms
- Analizar automáticamente estructuras con tipos de campo y valores
- Identificar objetos C++ mediante RTTI: *"Esto es un objeto CPlayer"*
- Desensamblar y analizar funciones
- Depurar invisiblemente con puntos de interrupción de hardware + hipervisor Ring -1
- ¡Y mucho más!
---
## Cómo Funciona
```mermaid
flowchart TD
AI[AI Agent: Claude/Cursor/Copilot]
AI -->|MCP Protocol - JSON-RPC over stdio| MCP
MCP[mcp_cheatengine.py - Python MCP Server]
MCP <-->|Named Pipe - Async| PIPE
PIPE["\\.\\pipe\\CE_MCP_Bridge_v99"]
PIPE <--> CE
subgraph CE[Cheat Engine - DBVM Mode]
subgraph LUA[ce_mcp_bridge.lua]
WORKER[Worker Thread - Blocking I/O]
MAIN[Main Thread - GUI + CE API]
WORKER <-->|Sync| MAIN
end
end
MAIN -->|Memory Access| TARGET[Target .exe]
```
---
## Instalación
```bash
pip install -r MCP_Server/requirements.txt
```
O manualmente:
```bash
pip install mcp pywin32
```
> [!NOTE]
> El modo de pipe nativo es **solo para Windows** porque usa Named Pipes (`pywin32`). Usa el transporte de relay TCP cuando el servidor MCP se ejecute fuera del entorno Windows que aloja Cheat Engine y no pueda abrir el named pipe directamente.
---
## Inicio Rápido
### 1. Cargar el Puente en Cheat Engine
1. Habilita DBVM en Cheat Engine si planeas usar herramientas DBVM.
2. Abre el motor Lua de Cheat Engine o el ejecutor de scripts.
- Preferido: `File` -> `Execute Script` -> abrir `MCP_Server/ce_mcp_bridge.lua` -> `Execute`.
- Si tu compilación de Cheat Engine no muestra `File` -> `Execute Script`, usa `Table` -> `Show Cheat Table Lua Script`, pega la línea `dofile(...)` a continuación, y ejecútala:
```lua
dofile([[C:\path\to\cheatengine-mcp-bridge\MCP_Server\ce_mcp_bridge.lua]])
```
Busca: `[MCP v12.0.0] MCP Server Listening on: CE_MCP_Bridge_v99`
### 2. Configurar el Cliente MCP
Agrega a tu configuración MCP (ej., `mcp_config.json`):
```json
{
"servers": {
"cheatengine": {
"command": "python",
"args": ["C:/path/to/MCP_Server/mcp_cheatengine.py"]
}
}
}
```
Reinicia el IDE para cargar la configuración del servidor MCP.
Para Codex, agrega un bloque de servidor TOML a `~/.codex/config.toml`:
```toml
[mcp_servers.cheatengine]
command = "python"
args = ['C:\path\to\cheatengine-mcp-bridge\MCP_Server\mcp_cheatengine.py']
```
Usa comillas simples para la ruta de Windows para que TOML trate las barras invertidas literalmente.
#### Transporte relay TCP
El relay TCP permite que `mcp_cheatengine.py` se comunique con Cheat Engine a través de un socket TCP en lugar de abrir el named pipe de Windows por sí mismo. Cheat Engine y el puente Lua aún se ejecutan en Windows, mientras que el servidor MCP puede ejecutarse en cualquier lugar que pueda alcanzar el relay: otro proceso de Windows, una VM, un contenedor, un host Linux o una máquina remota. Esto también se puede usar con WSL sin cambiar el puente Lua.
1. En Windows, carga `MCP_Server/ce_mcp_bridge.lua` en Cheat Engine como de costumbre.
2. En Windows, inicia el relay:
```powershell
python C:\path\to\cheatengine-mcp-bridge\MCP_Server\ce_tcp_relay.py --host 127.0.0.1 --port 9876
```
3. En el entorno donde se ejecutará el servidor MCP, instala la dependencia MCP sin `pywin32`, luego ejecuta/configura el servidor MCP con transporte TCP:
```bash
python3 -m pip install -r MCP_Server/requirements-tcp.txt
```
```bash
CE_MCP_TRANSPORT=tcp \
CE_MCP_HOST=127.0.0.1 \
CE_MCP_PORT=9876 \
python3 /path/to/cheatengine-mcp-bridge/MCP_Server/mcp_cheatengine.py
```
Para configuraciones de cliente MCP que soporten variables de entorno:
```json
{
"servers": {
"cheatengine": {
"command": "python3",
"args": ["/path/to/cheatengine-mcp-bridge/MCP_Server/mcp_cheatengine.py"],
"env": {
"CE_MCP_TRANSPORT": "tcp",
"CE_MCP_HOST": "127.0.0.1",
"CE_MCP_PORT": "9876"
}
}
}
}
```
Configura `--host` en el relay y `CE_MCP_HOST` en el servidor MCP con direcciones que coincidan con tu configuración de red. Mantén el relay vinculado solo a interfaces de confianza, porque cualquiera que pueda alcanzarlo puede controlar el puente de Cheat Engine.
### 3. Verificar Conexión
Usa la herramienta `ping` para verificar la conectividad:
```json
{"success": true, "version": "12.0.0", "message": "CE MCP Bridge Active"}
```
### 4. Empieza a Hacer Preguntas
```
"¿Qué proceso está adjunto?"
"Lee 16 bytes en la dirección base"
"Desensambla el punto de entrada"
```
---
## ~180 Herramientas MCP Disponibles
### Memoria
| Herramienta | Descripción |
|------|-------------|
| `read_memory`, `read_integer`, `read_string` | Lee cualquier tipo de dato |
| `read_pointer_chain` | Sigue rutas `[[base+0x10]+0x20]` |
| `scan_all`, `aob_scan` | Encuentra valores y patrones de bytes |
### Análisis
| Herramienta | Descripción |
|------|-------------|
| `disassemble`, `analyze_function` | Análisis de código |
| `dissect_structure` | Detecta automáticamente campos y tipos |
| `get_rtti_classname` | Identifica tipos de objetos C++ |
| `find_references`, `find_call_references` | Referencias cruzadas |
### Depuración
| Herramienta | Descripción |
|------|-------------|
| `set_breakpoint`, `set_data_breakpoint` | Puntos de interrupción de hardware |
| `start_dbvm_watch` | Rastreo invisible Ring -1 |
### Ciclo de Vida del Proceso
| Herramienta | Descripción |
|------|-------------|
| `open_process`, `get_process_list` | Adjuntar o enumerar procesos en ejecución |
| `create_process` | Iniciar un nuevo proceso bajo el control de CE |
| `pause_process`, `unpause_process` | Suspender/reanudar la ejecución del objetivo |
### Asignación de Memoria
| Herramienta | Descripción |
|------|-------------|
| `allocate_memory`, `free_memory` | Reservar y liberar memoria en el objetivo |
| `set_memory_protection`, `full_access` | Ajustar las banderas de protección de página |
### Inyección de Código
| Herramienta | Descripción |
|------|-------------|
| `inject_dll` | Cargar una DLL en el proceso objetivo |
| `execute_code`, `execute_method` | Ejecutar shellcode o métodos Lua de CE remotamente |
### Gestión de Símbolos
| Herramienta | Descripción |
|------|-------------|
| `register_symbol`, `get_symbol_info` | Crear y consultar símbolos nombrados |
| `enable_windows_symbols` | Habilitar resolución de símbolos PDB |
### Ensamblado / Compilación
| Herramienta | Descripción |
|------|-------------|
| `assemble_instruction` | Ensamblar una sola instrucción x86/x64 a bytes |
| `compile_c_code` | Compilar código fuente C en shellcode inyectado |
| `generate_api_hook_script` | Generar una plantilla de hook API de auto-ensamblador de CE |
### Automatización de Ventanas / GUI
| Herramienta | Descripción |
|------|-------------|
| `find_window` | Localizar una ventana por título o clase |
| `send_window_message` | Enviar mensajes `WM_*` a una ventana objetivo |
### Automatización de Entrada
| Herramienta | Descripción |
|------|-------------|
| `get_pixel` | Muestrear el color de un píxel en coordenadas de pantalla |
| `is_key_pressed`, `do_key_press` | Consultar y simular entrada de teclado |
### Cheat Table
| Herramienta | Descripción |
|------|-------------|
| `load_table`, `save_table` | Cargar/guardar archivos de cheat table `.CT` |
| `get_address_list` | Enumerar entradas en la cheat table activa |
### Modo Kernel (DBK / DBVM)
| Herramienta | Descripción |
|------|-------------|
| `dbk_get_cr3` | Leer el registro CR3 para el proceso objetivo |
| `read_process_memory_cr3` | Leer memoria física mediante bypass de CR3 |
Y muchos más en `AI_Context/MCP_Bridge_Command_Reference.md`
---
## Configuración Crítica
### Prevención de BSOD
> [!CAUTION]
> **Debes desactivar:** Cheat Engine → Configuración → Extra → **"Query memory region routines"**
>
> Activado: Causa BSOD `CLOCK_WATCHDOG_TIMEOUT` debido a conflictos con DBVM/Anti-Cheat al escanear páginas protegidas.
---
## Solución de Problemas
### Cheat Engine dice "demasiadas variables locales"
Carga el puente desde disco con `dofile(...)` en lugar de pegar el script completo en un script de cheat table. El puente también declara los manejadores de comandos como funciones globales intencionalmente; esto evita el límite de Cheat Engine de 200 variables locales por chunk de Lua cuando el puente completo se compila de una vez.
### El cliente MCP no puede conectarse
Verifica estos puntos en orden:
1. Cheat Engine está abierto y muestra `MCP Server Listening on: CE_MCP_Bridge_v99`.
2. El cliente MCP fue reiniciado después de agregar la configuración del servidor.
3. La ruta configurada `mcp_cheatengine.py` existe.
4. `pip install -r MCP_Server/requirements.txt` ha instalado tanto `mcp` como `pywin32`.
5. Ejecuta la herramienta `ping` de MCP. Una conexión exitosa devuelve `success: true` y la versión del puente. `process_id: 0` es normal hasta que Cheat Engine se adjunte a un proceso objetivo.
---
## Variables de Entorno
| Variable | Predeterminado | Propósito |
|----------|---------|---------|
| `CE_MCP_TIMEOUT` | `30` | Tiempo de espera (segundos) para cada llamada de herramienta MCP. |
| `CE_MCP_ALLOW_SHELL` | *sin asignar* | Establecer a `1` para habilitar las herramientas `run_command` / `shell_execute`. **Riesgo de ejecución de código arbitrario** — déjalo sin asignar por defecto. |
---
## Ejemplos de Flujos de Trabajo
**Encontrando un valor:**
```
You: "Scan for gold: 15000" → AI finds 47 results
You: "Gold changed to 15100" → AI filters to 3 addresses
You: "What writes to the first one?" → AI sets hardware BP
You: "Disassemble that function" → Full AddGold logic revealed
```
**Entendiendo una estructura:**
```
You: "What's at [[game.exe+0x1234]+0x10]?"
AI: "RTTI: CPlayerInventory"
AI: "0x00=vtable, 0x08=itemCount(int), 0x10=itemArray(ptr)..."
```
---
## Estructura del Proyecto
```
CLAUDE.md # Guía del agente Claude Code (este repositorio)
README.md # Documentación para el usuario
MCP_Server/
├── mcp_cheatengine.py # Servidor MCP Python (FastMCP)
├── ce_mcp_bridge.lua # Puente Lua de Cheat Engine
└── test_mcp.py # Suite de pruebas
AI_Context/
├── BATCH_WORKER_BRIEFING.md # Especificaciones de tareas de trabajadores paralelos (revisión v12)
├── MCP_Bridge_Command_Reference.md # Referencia de comandos MCP
├── CE_LUA_Documentation.md # Documentación oficial completa de CheatEngine 7.6
└── AI_Guide_MCP_Server_Implementation.md # Documentación técnica completa para el agente IA
```
---
## Pruebas
Ejecutar la prueba:
```bash
python MCP_Server/test_mcp.py
```
Salida esperada:
```
✅ Memory Reading: 6/6 tests passed
✅ Process Info: 4/4 tests passed
✅ Code Analysis: 8/8 tests passed
✅ Breakpoints: 4/4 tests passed
✅ DBVM Functions: 3/3 tests passed
✅ Utility Commands: 11/11 tests passed
⏭️ Skipped: 1 test (generate_signature)
────────────────────────────────────
Total: 36/37 PASSED (100% success)
```
---
## En Resumen
Ya no necesitas ser un experto. Solo haz las preguntas correctas.
⚠️ AVISO EDUCATIVO
Este código es solo para fines educativos y de investigación. Está creado para mostrar las capacidades del Model Context Protocol (MCP) y la depuración basada en LLM. No apruebo el uso de estas herramientas para hacking malicioso, trampas en juegos multijugador o violación de Términos de Servicio. Esta es una demostración de automatización de ingeniería de software.