Metadata-Version: 2.4
Name: iflow-mcp_0xhackerfren-frida-game-hacking-mcp
Version: 1.1.0
Summary: MCP server for game hacking with Frida - Cheat Engine-like memory scanning, hooking, and code injection
Project-URL: Homepage, https://github.com/0xhackerfren/frida-game-hacking-mcp
Project-URL: Documentation, https://github.com/0xhackerfren/frida-game-hacking-mcp#readme
Project-URL: Repository, https://github.com/0xhackerfren/frida-game-hacking-mcp
Project-URL: Issues, https://github.com/0xhackerfren/frida-game-hacking-mcp/issues
Author-email: 0x_hackerfren <0xhackerfren@gmail.com>
License: MIT License
        
        Copyright (c) 2024
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
License-File: LICENSE
Keywords: cheat-engine,dynamic-instrumentation,frida,game-hacking,hooking,mcp,memory-scanning,reverse-engineering
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Requires-Dist: frida-tools>=12.0.0
Requires-Dist: frida>=16.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: pywin32>=306; sys_platform == 'win32'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

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

![MCP](https://img.shields.io/badge/MCP-Compatible-blue)
![Python](https://img.shields.io/badge/Python-3.10+-green)
![Frida](https://img.shields.io/badge/Frida-16.0+-orange)
![License](https://img.shields.io/badge/License-MIT-yellow)

## 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.*
