Metadata-Version: 2.4
Name: frida-mcp-re
Version: 0.3.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

## What's New in 0.3.0

- **7 new tools** — typed memory read/write, hex dump, pointer chain, address watcher, session list/close
- **Full async refactor** — all tools now use `threading.Event` instead of fixed `time.sleep` delays (up to 10× faster responses)
- **Central `_run_script` helper** — eliminates ~250 lines of duplicated boilerplate across all modules
- **Bug fix** — `read_memory` was missing its `@mcp.tool()` decorator and was never registered
- **Better error reporting** — all tools now return structured `timed_out` errors with clear messages

## Features

- Built with the official MCP Python SDK
- **61+ tools** covering all major Frida capabilities
- Full VM support: Java/Android, Mono, IL2CPP (Unity), Lua, Python embedded, V8/Node.js
- Game engine reverse engineering support
- Event-driven synchronization — no wasted wait time

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

### 🗂️ Session Management (2 tools) ⭐ New
| Tool | Description |
|------|-------------|
| `list_sessions` | List all active sessions with PID, timestamp and hook count |
| `close_session` | Detach, unload all scripts and clean up a session |

### 📦 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 (11 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 |
| `read_memory_typed` | Read a typed scalar value (int8…double…pointer) ⭐ New |
| `write_memory_typed` | Write a typed scalar value without encoding bytes ⭐ New |
| `dump_memory_region` | Hex editor-style dump: offset + hex + ASCII ⭐ New |
| `follow_pointer_chain` | Follow a multi-level pointer chain with all intermediate steps ⭐ New |
| `watch_address` | Poll a memory address and report value changes ⭐ New |

### 🪝 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 (16 tools)
| Tool | Description |
|------|-------------|
| `detect_embedded_vm` | Auto-detect embedded VMs (Lua, LuaJIT, Python, Mono, IL2CPP, V8, JVM, Chakra) |
| `mono_list_assemblies` | Detect Mono/.NET runtime and 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 at offset |
| `il2cpp_hook_method` | Hook an IL2CPP native method |
| `lua_list_globals` | List Lua global variables |
| `lua_exec` | Execute Lua code in the embedded runtime |
| `python_detect` | Detect embedded CPython runtime |
| `python_exec` | Execute Python code in the embedded interpreter |
| `python_hook_function` | Hook PyEval_EvalCode to trace Python execution |
| `python_import_module` | Import a Python module in the embedded interpreter |
| `v8_detect` | Detect V8 / Node.js engine |
| `v8_list_scripts` | List JavaScript scripts loaded in V8 |
| `v8_hook_script_compile` | Hook Node.js script compilation entry points |
| `v8_enumerate_exports` | Enumerate V8/Node.js module exports |

### 🖥️ 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-re
```

### 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
- **Python embedded** — Execute and trace CPython runtimes embedded in games/apps
- **V8 / Node.js** — Detect, enumerate and hook embedded V8 runtimes
- **Custom VM detection** — Auto-detects Lua, LuaJIT, Python, V8, Chakra, Mono, IL2CPP, JVM

### Typical Game RE Workflow

```
1. attach to game process     → attach_to_process
2. create session             → create_interactive_session
3. detect VM / engine         → detect_embedded_vm
4. map loaded modules         → list_modules
5. AOB scan                   → scan_memory_pattern  (ViewMatrix, EntityList…)
6. follow pointer chain       → follow_pointer_chain (static base → offsets)
7. read typed values          → read_memory_typed    (health, ammo, position)
8. watch address changes      → watch_address        (live monitoring)
9. hook game logic            → hook_function / java_hook_method / il2cpp_hook_method
10. dump struct layout        → dump_memory_region
11. patch values              → write_memory_typed
12. close when done           → close_session
```

### New Tools in Action

```python
# Read player health (float at known address)
read_memory_typed(session_id, "0x7FF12340", type="float")

# Follow pointer chain: base → +0x0 → +0x58 → +0x1A0 (player struct)
follow_pointer_chain(session_id, "0x14B8C2A0", offsets=[0x0, 0x58, 0x1A0])

# Watch ammo counter live (poll every 200ms for 10 seconds)
watch_address(session_id, "0x7FF12344", type="int32", interval_ms=200, duration_ms=10000)

# Hex dump 256 bytes of a struct
dump_memory_region(session_id, "0x7FF12300", size=256)

# Patch: set health to 9999
write_memory_typed(session_id, "0x7FF12340", type="float", value="9999.0")

# Clean up
close_session(session_id)
```

## Architecture

```
frida_mcp/
├── server.py          # FastMCP instance + shared state + _run_script helpers
├── cli.py             # STDIO entrypoint for Claude Desktop
└── tools/
    ├── processes.py   # Device & process management (10 tools)
    ├── sessions.py    # Interactive REPL sessions (3 tools)
    ├── modules.py     # Module & symbol analysis (4 tools)
    ├── memory.py      # Memory read/write/scan (9 tools)
    ├── hooks.py       # Hooking, tracing, Stalker (4 tools)
    ├── native.py      # NativeFunction / NativeCallback (2 tools)
    ├── java_bridge.py # Java/Android bridge (6 tools)
    ├── vm_support.py  # Mono, IL2CPP, Lua, Python, V8 (16 tools)
    └── advanced.py    # Session mgmt + advanced memory (7 tools)
```

## License

MIT
