# Frida Game Hacking MCP
A Model Context Protocol (MCP) server that provides **Cheat Engine-like capabilities** for game hacking through [Frida](https://frida.re/). Enables AI assistants and automation tools to perform memory scanning, value modification, pattern matching, function hooking, and code injection.
## Features
### Memory Operations (Cheat Engine Style)
- **Value Scanning**: Find values in memory by type (int8-64, float, double, string)
- **Scan Refinement**: Narrow results with `scan_next`, `scan_changed`, `scan_unchanged`
- **Pattern Scanning**: Array of Bytes (AoB) with wildcard support (`??`)
- **Memory Read/Write**: Read and modify memory with type awareness
### Function Hooking & Code Injection
- **Intercept Functions**: Hook with `onEnter`/`onLeave` JavaScript callbacks
- **Replace Functions**: Make functions return custom values
- **Module Hooking**: Hook by `module!function` name
- **Symbol Resolution**: Resolve exports to addresses
### Process Management
- **Process Enumeration**: List and filter running processes
- **Attach/Detach**: Connect to running processes
- **Spawn & Resume**: Start processes suspended for early hooking
### Debugging
- **Breakpoints**: Software breakpoints via hooks
- **Register Access**: Read CPU registers at breakpoints
- **Module Analysis**: List modules, exports, imports
### Window Interaction (Windows)
- **Screenshot Capture**: Take screenshots of game windows
- **Keyboard Input**: Send keystrokes to game windows
- **Window Management**: List, focus, and interact with windows
## Installation
```bash
# Install from PyPI (coming soon)
pip install frida-game-hacking-mcp
# Or install from source
git clone https://github.com/0xhackerfren/frida-game-hacking-mcp.git
cd frida-game-hacking-mcp
pip install -e .
```
### Requirements
- Python 3.10+
- Frida 16.0+
- pywin32, pillow (Windows, for screenshot features)
```bash
pip install frida frida-tools mcp pillow
# On Windows, also install:
pip install pywin32
```
## Quick Start
### Run the MCP Server
```bash
# Run directly
python -m frida_game_hacking_mcp
# Or use the entry point
frida-game-hacking-mcp
```
### Configure with Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"frida-game-hacking": {
"command": "python",
"args": ["-m", "frida_game_hacking_mcp"]
}
}
}
```
### Configure with Other MCP Clients
The server uses stdio transport by default. Connect using:
- Command: `python -m frida_game_hacking_mcp`
- Transport: stdio
## Usage Examples
### Cheat Engine Workflow: Find and Modify Health
```
1. List processes and find your game
> list_processes("game")
2. Attach to the game
> attach("game.exe")
3. Initial scan for current health value (e.g., 100)
> scan_value(100, "int32")
Found: 58,869 addresses
4. Take damage in game (health now 95)
> scan_next(95)
Narrowed to: 1,419 addresses
5. Repeat until you find the address
> scan_next(90)
Narrowed to: 3 addresses
6. Get results and modify
> get_scan_results()
> write_memory("0x12345678", "E7030000") # 999 in little-endian
```
### Array of Bytes Pattern Scanning
```
# Find code pattern (works across game updates)
> attach("game.exe")
> scan_pattern("89 47 44 ?? ?? 5B 7A", "r-x")
Found: 2 matches
# ?? = wildcard bytes
# "r-x" = executable memory regions
```
### Function Hooking
```
# Hook a function and log calls
> hook_function("0x401234",
on_enter="console.log('Args:', args[0], args[1]);",
on_leave="console.log('Return:', retval);")
# Make a function always return success
> replace_function("0x401234", 1)
# Hook by module and function name
> intercept_module_function("game.dll", "CheckLicense",
on_leave="retval.replace(1);")
```
### Early Hooking (Spawn Suspended)
```
# Start process suspended
> spawn("C:/Games/game.exe")
# Set up hooks before code runs
> hook_function("0x401234", on_enter="...")
# Resume execution
> resume()
```
## Available Tools (42 Total)
### Process Management (6)
| Tool | Description |
|------|-------------|
| `list_processes` | Enumerate running processes |
| `attach` | Attach to process by name or PID |
| `detach` | Detach from current process |
| `spawn` | Start process suspended |
| `resume` | Resume spawned process |
| `get_session_info` | Get current session status |
### Memory Operations (10)
| Tool | Description |
|------|-------------|
| `read_memory` | Read bytes at address |
| `write_memory` | Write bytes/values to address |
| `scan_value` | Initial scan for exact value |
| `scan_next` | Narrow scan with new value |
| `scan_changed` | Find changed values |
| `scan_unchanged` | Find unchanged values |
| `scan_pattern` | AoB pattern scan with wildcards |
| `get_scan_results` | Get current scan results |
| `clear_scan` | Reset scan state |
| `list_memory_regions` | List memory regions |
### Module Information (5)
| Tool | Description |
|------|-------------|
| `list_modules` | List loaded modules/DLLs |
| `get_module_info` | Get module details |
| `get_module_exports` | List module exports |
| `get_module_imports` | List module imports |
| `resolve_symbol` | Resolve symbol to address |
### Function Hooking (6)
| Tool | Description |
|------|-------------|
| `hook_function` | Hook with callbacks |
| `unhook_function` | Remove hook |
| `replace_function` | Replace function return |
| `hook_native_function` | Hook with calling convention |
| `list_hooks` | List active hooks |
| `intercept_module_function` | Hook by module!function |
### Debugging (4)
| Tool | Description |
|------|-------------|
| `set_breakpoint` | Set software breakpoint |
| `remove_breakpoint` | Remove breakpoint |
| `list_breakpoints` | List breakpoints |
| `read_registers` | Read CPU registers |
### Script Management (3)
| Tool | Description |
|------|-------------|
| `load_script` | Load custom Frida JS |
| `unload_script` | Unload script |
| `call_rpc` | Call script RPC export |
### Window Interaction (5) - Windows Only
| Tool | Description |
|------|-------------|
| `list_windows` | Enumerate visible windows |
| `screenshot_window` | Capture window to PNG/base64 |
| `screenshot_screen` | Capture screen or region |
| `send_key_to_window` | Send keystrokes to window |
| `focus_window` | Bring window to foreground |
### Standard MCP (3)
| Tool | Description |
|------|-------------|
| `list_capabilities` | List all tools |
| `get_documentation` | Get help and examples |
| `check_installation` | Verify Frida installed |
## Value Types
| Type | Size | Description |
|------|------|-------------|
| `int8` | 1 byte | Signed byte |
| `uint8` | 1 byte | Unsigned byte |
| `int16` | 2 bytes | Signed short |
| `uint16` | 2 bytes | Unsigned short |
| `int32` | 4 bytes | Signed int (most common) |
| `uint32` | 4 bytes | Unsigned int |
| `int64` | 8 bytes | Signed long |
| `uint64` | 8 bytes | Unsigned long |
| `float` | 4 bytes | Single precision |
| `double` | 8 bytes | Double precision |
| `string` | Variable | Null-terminated string |
## Scan Regions
| Region | Description |
|--------|-------------|
| `rw-` | Read-write data (heap, stack, globals) - default for value scans |
| `r-x` | Executable code - default for pattern scans |
| `rwx` | Read-write-execute (rare, often exploitable) |
| `r--` | Read-only data |
## Platform Support
- **Windows**: Native support
- **Linux**: Native support
- **macOS**: Native support
- **Android**: Via frida-server
- **iOS**: Via frida-server (jailbroken)
## Use Cases
- **Game Hacking**: Memory editing, value modification, trainer development
- **Security Research**: Vulnerability analysis, exploit development
- **Reverse Engineering**: Runtime analysis, API hooking
- **Software Testing**: Fault injection, behavior modification
- **Malware Analysis**: Dynamic analysis in sandboxed environments
## Security Notice
This tool is intended for:
- Educational purposes
- Security research on software you own or have permission to test
- Game modding in single-player/offline contexts
**Do not use for**:
- Cheating in online multiplayer games
- Circumventing software protections illegally
- Any malicious purposes
## Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Submit a pull request
## License
MIT License - see [LICENSE](LICENSE)
## Credits
- Built on [Frida](https://frida.re/) by Ole Andre Vadla Ravnas
- MCP protocol by [Anthropic](https://github.com/anthropics/anthropic-cookbook/tree/main/misc/model_context_protocol)
- Inspired by [Cheat Engine](https://www.cheatengine.org/) by Dark Byte
## Links
- [Frida Documentation](https://frida.re/docs/)
- [MCP Specification](https://spec.modelcontextprotocol.io/)
- [Report Issues](https://github.com/0xhackerfren/frida-game-hacking-mcp/issues)
---
*Built for AI-assisted game hacking and security research.*