Metadata-Version: 2.4
Name: frida-mcp-re
Version: 0.2.0
Summary: Model Context Protocol implementation for Frida
License: MIT
License-File: LICENSE
Requires-Python: >=3.8
Requires-Dist: frida>=16.0.0
Requires-Dist: mcp>=1.5.0
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Description-Content-Type: text/markdown

# Frida MCP

A Model Context Protocol (MCP) implementation for Frida dynamic instrumentation toolkit.

## Overview

This package provides an MCP-compliant server for Frida, enabling AI systems to interact with mobile and desktop applications through Frida's dynamic instrumentation capabilities. It uses the official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) to enable seamless integration with AI applications like Claude Desktop.

## Demo

https://github.com/user-attachments/assets/5dc0e8f5-5011-4cf2-be77-6a77ec960501

## Features

- Built with the official MCP Python SDK
- **26+ tools** covering all major Frida capabilities
- Full VM support: Java/Android, Mono, IL2CPP (Unity), Lua, Python embedded
- Game engine reverse engineering support

## Tool Categories

### 🔧 Process & Device Management (10 tools)
| Tool | Description |
|------|-------------|
| `enumerate_processes` | List all running processes on device |
| `enumerate_devices` | List all connected devices (USB, remote) |
| `get_device` | Get a device by ID |
| `get_usb_device` | Get the connected USB device |
| `get_local_device` | Get the local device |
| `get_process_by_name` | Find a process by name (partial, case-insensitive) |
| `attach_to_process` | Attach to a process by PID |
| `spawn_process` | Spawn a new process or app |
| `resume_process` | Resume a suspended process |
| `kill_process` | Kill a process by PID |

### 💬 Interactive Sessions (3 tools)
| Tool | Description |
|------|-------------|
| `create_interactive_session` | Create a REPL-like Frida session with a process |
| `execute_in_session` | Execute JavaScript code in an active session |
| `get_session_messages` | Retrieve messages from persistent scripts |

### 📦 Module & Symbol Analysis (6 tools)
| Tool | Description |
|------|-------------|
| `list_modules` | List all loaded modules/libraries |
| `find_module_by_name` | Find a module by name (partial match) |
| `list_exports` | List all exported symbols of a module |
| `list_imports` | List all imported symbols of a module |
| `resolve_symbol` | Resolve the absolute address of an export |
| `find_symbol_by_pattern` | Search exports by regex pattern |

### 💾 Memory Operations (6 tools)
| Tool | Description |
|------|-------------|
| `read_memory` | Read raw bytes from a memory address |
| `write_memory` | Write bytes to a memory address |
| `scan_memory_pattern` | AOB scan with wildcard support (`??`) |
| `read_pointer` | Read a pointer-sized value |
| `read_string_at` | Read null-terminated string (UTF-8/16/ANSI) |
| `enumerate_memory_ranges` | List all memory regions with permissions |

### 🪝 Hooking & Tracing (4 tools)
| Tool | Description |
|------|-------------|
| `hook_function` | Persistent Interceptor hook (args + retval) |
| `enumerate_threads` | List all threads with state and context |
| `get_thread_backtrace` | Get backtrace for a specific thread |
| `stalker_trace_thread` | Trace a thread's execution with Stalker |

### ⚙️ Native Calls (2 tools)
| Tool | Description |
|------|-------------|
| `call_native_function` | Call a native function at an address |
| `install_native_callback` | Replace a function with a NativeCallback |

### ☕ Java / Android Bridge (6 tools)
| Tool | Description |
|------|-------------|
| `java_list_classes` | List all loaded Java classes (with filter) |
| `java_list_methods` | List all methods of a Java class |
| `java_hook_method` | Hook a Java method (persistent) |
| `java_get_field_value` | Get a Java field value (static or instance) |
| `java_set_field_value` | Set a Java field value |
| `java_call_method` | Call a Java method directly |

### 🎮 VM & Game Engine Support (6 tools)
| Tool | Description |
|------|-------------|
| `detect_embedded_vm` | Auto-detect embedded VMs (Lua, Python, Mono, IL2CPP, V8, JVM) |
| `mono_list_assemblies` | List Mono/.NET assemblies |
| `il2cpp_find_class` | Find an IL2CPP class by namespace and name |
| `il2cpp_find_method` | Find a method in an IL2CPP class |
| `il2cpp_read_field` | Read a field from an IL2CPP object |
| `il2cpp_hook_method` | Hook an IL2CPP native method |
| `lua_list_globals` | List Lua global variables |
| `lua_exec` | Execute Lua code in the embedded runtime |

### 🖥️ Process Info (1 tool)
| Tool | Description |
|------|-------------|
| `get_process_architecture` | Get arch, platform, pointer size, page size |

## Installation

### Prerequisites

- Python 3.8 or later
- pip package manager
- Frida 16.0.0 or later

### Quick Install

```bash
pip install frida-mcp
```

### Development Install

```bash
git clone https://github.com/yourusername/frida-mcp.git
cd frida-mcp
pip install -e ".[dev]"
```

## Claude Desktop Integration

Add to your Claude Desktop config file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "frida": {
      "command": "frida-mcp"
    }
  }
}
```

## Game Reverse Engineering

Frida MCP is specifically designed for reverse engineering games that use embedded VMs or custom scripting engines:

### Supported Engines & VMs
- **Unity (Mono)** - Hook managed methods, read/write fields
- **Unity (IL2CPP)** - Native compiled code, class/method finder, field reader
- **Android (Java)** - Full Java bridge: class listing, method hooking, field access
- **Lua-based games** - Execute Lua code inside the game's Lua state
- **Custom VM detection** - Auto-detects Lua, LuaJIT, Python, V8, Chakra

### Typical Game RE Workflow

```
1. attach to game process → create_interactive_session
2. detect_embedded_vm → identify scripting engine
3. list_modules → map loaded DLLs
4. scan_memory_pattern (AOB) → find ViewMatrix / EntityList
5. read_memory → validate structure layout
6. hook_function / java_hook_method → trace game logic
7. il2cpp_find_class + il2cpp_find_method → navigate managed code
```

## License

MIT
