# Frida MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes [Frida](https://frida.re/) dynamic instrumentation capabilities to AI assistants like **Claude Code**, **Claude Desktop**, and any other MCP-compatible client.

> **What this enables:** Your AI assistant can list processes, attach to them, hook functions, read memory, and execute arbitrary instrumentation scripts — all through structured tool calls, without writing boilerplate.

## Features

- **Process management** — list, attach, detach from running processes
- **Module introspection** — enumerate loaded DLLs/modules, find exported function addresses
- **Memory access** — read raw memory and strings (UTF-8, UTF-16, ANSI) from the target process
- **Function hooking** — intercept function calls, trace arguments and return values
- **Batch hooking** — hook multiple functions simultaneously
- **Arbitrary scripting** — execute custom Frida JavaScript in the target process

## Installation

### Prerequisites

- Python 3.10+
- [Frida](https://frida.re/docs/installation/) tools installed on your system
- (Windows) A Frida server running on the target device if targeting mobile/remote

### Install from source

```bash
git clone https://github.com/cengziyang22-bit/frida-mcp.git
cd frida-mcp
pip install -e .
```

### Quick install via pip

```bash
pip install git+https://github.com/cengziyang22-bit/frida-mcp.git
```

## Configuration

### Claude Code

Add to `~/.mcp.json`:

```json
{
  "mcpServers": {
    "frida": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "frida_mcp.server"]
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "frida": {
      "command": "python",
      "args": ["-m", "frida_mcp.server"]
    }
  }
}
```

## Tools Reference

| Tool | Description |
|------|-------------|
| `list_processes` | List running processes visible to Frida |
| `attach_process` | Attach to a process by name or PID |
| `detach_process` | Detach from the current process |
| `get_process_info` | Get info about the attached process |
| `list_modules` | List loaded modules/DLLs in the target process |
| `find_export` | Find the address of an exported function |
| `read_memory` | Read raw bytes from process memory |
| `read_string` | Read a string from process memory |
| `hook_function` | Hook a function and watch its calls |
| `hook_functions_batch` | Hook multiple functions simultaneously |
| `run_script` | Execute arbitrary Frida JavaScript in the target |

## Usage Examples

### 1. Find and attach to a process

```
attach_process("notepad.exe")
```

### 2. List loaded modules

```
list_modules(filter_name="kernel32")
```

### 3. Hook a Windows API function

```
hook_function("MessageBoxW", duration_seconds=10)
```

Then trigger a message box in the target app — all calls are captured with timestamps and arguments.

### 4. Read a string from memory

```
read_string("0x7ffb5fa80000", encoding="utf16")
```

### 5. Run a custom Frida script

```
run_script("""
  Process.enumerateModules().filter(m => m.name.includes('sqlite'))
    .forEach(m => send(m.name + ' @ ' + m.base));
""")
```

### 6. Batch hook multiple functions

```
hook_functions_batch("WriteFile,ReadFile,CreateFileW", duration_seconds=5)
```

## Architecture

```
frida-mcp/
├── frida_mcp/
│   ├── __init__.py
│   └── server.py      # MCP server with all 11 tools
├── pyproject.toml      # Project metadata and dependencies
├── README.md
└── LICENSE
```

The server uses [FastMCP](https://github.com/jlowin/fastmcp) over stdio transport. All tool state (attached process, hook queues) is session-scoped and thread-safe.

## Frida Version Compatibility

Built and tested against **Frida 17.x**. Key API changes from Frida 16.x:

| Old (Frida 16) | New (Frida 17) |
|---|---|
| `Module.enumerateModules()` | `Process.enumerateModules()` |
| `Module.getGlobalExportByName(mod, name)` | `Module.getGlobalExportByName(name)` |
| `ptr("0x...")` | `new NativePointer(...)` |

## Security Considerations

- Frida requires **elevated privileges** to attach to processes on most platforms
- Hooking and memory manipulation can **crash the target process**
- Only attach to processes you own or have explicit permission to instrument
- The `run_script` tool executes arbitrary JavaScript in the target process — use with caution

## License

MIT © 2025

## Acknowledgments

- [Frida](https://frida.re/) — the dynamic instrumentation toolkit that makes this possible
- [FastMCP](https://github.com/jlowin/fastmcp) — elegant Python MCP framework
- [Model Context Protocol](https://modelcontextprotocol.io/) — Anthropic's open standard for AI-tool integration