Skip to main content
Glama

emu-mcp

CI License: MIT Python 3.10+

emu-mcp is an MCP server that lets an AI verify reverse-engineering guesses by emulating single functions in isolation with Unicorn. No syscalls, filesystem, or network are emulated; unknown calls stop execution and report their address.

Turkish / Türkçe: emu-mcp, Unicorn motoru ile tek bir fonksiyonu izole olarak emulate eden bir MCP sunucusudur. Reverse engineering tahminlerini doğrulamak için kullanılır. Hiçbir syscall, dosya sistemi veya ağ emüle edilmez; bilinmeyen çağrılar durdurulur ve adresi raporlanır.


Why

When reverse-engineering a binary, you form hypotheses about what a function does. emu-mcp lets you run that function with known inputs in an isolated emulator and check the result, instead of trusting the guess.

Supported architectures: x86, x64, arm, arm64.


Related MCP server: Antardrishti

Features

  • Parse ELF / PE / Mach-O binaries with LIEF and auto-detect architecture.

  • Emulate a single function with arguments passed per calling convention (System V AMD64, ARM64, etc.).

  • Pre-write memory inputs, read/write memory, stub libc/API calls.

  • Trace executed addresses and memory reads/writes (paginated with limit/offset).

  • Hard limits on instruction count and wall-clock time to prevent runaway emulation.

  • x86/x64 stack alignment (RSP 8 mod 16) and ARM SP alignment.

  • Floating-point (XMM) argument and return-value stub support.

  • Clean, machine-readable JSON output suitable for AI agents.

  • No syscalls, filesystem, or network are emulated.

  • Unknown calls stop execution and report their address.


Install

From PyPI (when published)

pip install emu-mcp

From GitHub

pip install git+https://github.com/RivaExits0/emu-mcp.git

From Source

git clone https://github.com/RivaExits0/emu-mcp.git
cd emu-mcp
pip install -e .[dev]    # or just `pip install -e .` for production

System requirements (Linux): gcc-x86-64-linux-gnu and binutils for building test binaries. On Windows, cross-compilation is not required for the test suite.


Run

emu-mcp
# or
python -m emu_mcp

The server speaks MCP over stdio.


Claude Desktop Integration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "emu-mcp": {
      "command": "emu-mcp",
      "args": [],
      "env": {}
    }
  }
}

Windows: If installed via pip, emu-mcp should be on PATH. Otherwise use full path: C:\\path\\to\\emu-mcp\\.venv\\Scripts\\emu-mcp.exe.


OpenCode Integration

Add to opencode.json:

{
  "mcp": {
    "emu": {
      "type": "local",
      "command": ["emu-mcp"],
      "enabled": true
    }
  }
}

MCP Tools

Tool

Description

When to call

emu_load(path, arch=None)

Parse a binary and map its segments into Unicorn memory.

First, before any emulation.

emu_run(func_addr, args=[], mem_inputs={}, max_insns=100000)

Emulate one function, return value + registers.

After emu_load.

emu_trace(func_addr, args=[], mem_inputs={}, limit=50, offset=0)

Trace addresses and memory access (paginated).

After emu_run to see execution flow.

`emu_read_mem(addr, length, fmt="hex"

"ascii")`

Read up to 4096 bytes from emulated memory.

emu_write_mem(addr, data_hex)

Write hex data to emulated memory.

To set up inputs before emu_run.

emu_hook_call(addr, return_value, name=None)

Stub a call (malloc, strlen, …) with a fixed return value.

To avoid calling unsupported libc functions.

emu_reset()

Reset the emulation session (clear memory, registers, hooks).

Between unrelated emulations.


Tool: emu_load

Example call:

{"tool": "emu_load", "args": {"path": "tests/sample_x64", "arch": null}}

Example output:

{
  "format": "elf",
  "arch": "x64",
  "entry": "0x401000",
  "segments": [
    {"vaddr": "0x400000", "memsz": 0x2000, "filesz": 0x1f00, "offset": 0}
  ],
  "base_address": "0x400000"
}

Tool: emu_run

Example call:

{"tool": "emu_run", "args": {"func_addr": "0x4011d0", "args": [5, 7], "max_insns": 100000}}

Example output:

{
  "return_value": 12,
  "stop_reason": "returned",
  "instruction_count": 11,
  "registers": {"rax": 12, "rip": "0x4011db", ...}
}

Tool: emu_trace

Example call:

{"tool": "emu_trace", "args": {"func_addr": "0x4011d0", "args": [5, 7], "limit": 50, "offset": 0}}

Example output:

stop: returned, insns: 11
called addresses:
  0x4011d0
  0x4011d4
  0x4011d5
  0x4011d8

Supported Architectures

Architecture

Calling Convention

Status

x86 (32-bit)

cdecl

✅

x64 (64-bit)

System V AMD64

✅

ARM (32-bit)

AAPCS

✅

ARM64 (AArch64)

AAPCS64

✅


Testing

# Build test binaries (Linux only)
make all

# Run test suite
pytest -q
# or
make test

# Run demo
make demo
# or
python examples/demo.py

Runs tests/test_emu.py, tests/test_hard.py, and examples/demo.py.

The hard suite covers:

  • Recursion (factorial)

  • Function pointers (indirect calls)

  • Stack arguments (many-arg functions)

  • Structs by pointer

  • In-place memory modification

  • Nested calls

  • Libc hooks (strcmp)

  • Floating point (XMM registers)

  • Error cases (unmapped memory, instruction limit)

Demo

make demo

Expected output:

=== Demo 1: add(5, 7) ===
result=12 stop=returned insns=11
...
ALL DEMO CHECKS PASSED

Architecture

src/emu_mcp/
├── server.py      MCP tool definitions (stdio transport)
├── emulator.py    Unicorn engine, calling conventions, hooks, tracing
├── loader.py      LIEF-based binary parsing and segment mapping
└── platform_utils.py  Cross-platform paths, subprocess, file I/O

Pagination (limit / offset)

emu_trace supports limit and offset for long trace lists:

  • limit: maximum number of trace lines to return (default 50)

  • offset: number of trace lines to skip (default 0)


Security Notes

  • No syscalls, filesystem, or network are emulated.

  • Unknown calls stop execution and report their address.

  • Instruction count and wall-clock timeouts prevent runaway emulation.

  • Memory is isolated per session; emu_reset clears state.


Limitations

  • No real syscall emulation; unknown calls stop execution.

  • No filesystem or network access inside the emulator.

  • Floating-point support is limited to XMM register stubs.

  • Stack alignment follows System V AMD64 ABI; other ABIs may need adjustment.


  • forge-mcp — Game modding toolkit (hex, PE, APK, Unity, Unreal, tables). Use for hex editing, signature generation, APK repacking.

  • henry-mcp — Static compatibility analysis for EXE/DLL/APK/Kotlin. Use for checking module compatibility.

  • crash-mcp — Crash dump analysis (ELF core + Windows minidump). Use for post-mortem debugging.


📦 Release

  • Latest: v0.1.0

  • Install from release: pip install git+https://github.com/RivaExits0/emu-mcp.git@v0.1.0

Create Release

git tag -a v0.1.0 -m "emu-mcp v0.1.0: Initial release"
git push origin v0.1.0

License

MIT — see LICENSE.

Available Tools

7 tools
emu_hook_callA

Stub a function at addr: skip it and return return_value.

Use for libc/API stubs such as malloc, strlen, printf. Prevents unknown-call stops. A float return_value is returned in the floating point return register. Returns confirmation.

Inputs: addr (required), return_value (required), name. Returns: result

emu_loadA

Load a binary (ELF/PE/Mach-O) with LIEF and map its segments into Unicorn memory.

Use this first, before emulating any function. Architecture is auto-detected (x86, x64, arm, arm64) unless arch is provided. Resets any previous session.

Inputs: path (required), arch. Returns: result

emu_read_memB

Read up to 4096 bytes from emulated memory.

fmt is "hex" or "ascii". Use to inspect memory after/before a run.

Inputs: addr (required), length (required), fmt. Returns: result

emu_resetA

Reset the emulator session (unload binary, clear hooks and memory).

Inputs: no named parameters. Returns: result

emu_runA

Emulate a single function in isolation and return its result.

Use after you have guessed what a function does, to verify the guess against known inputs. args are passed per calling convention (floats go to the floating point argument registers); mem_inputs maps addresses (hex/dec strings) to hex byte data pre-written to memory. Returns return value, main registers, instruction count and stop reason. No syscalls/filesystem/network are emulated; unknown calls stop execution.

Inputs: func_addr (required), args, max_insns, mem_inputs, +1 more. Returns: result

emu_traceB

Trace an emulated function: executed addresses and memory read/write summary.

Use to understand control flow or memory access of a function. At most limit addresses are printed per page; use offset to page through long address lists.

Inputs: func_addr (required), args, limit, offset, +3 more. Returns: result

emu_write_memC

Write hex data to emulated memory. Returns number of bytes written.

Inputs: addr (required), data_hex (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool maps to a distinct action in the emulation lifecycle: load, reset, run, trace, read memory, write memory, and hook a call. The only near-overlap is emu_run vs emu_trace, but their descriptions clearly separate result/register reporting from address-level control-flow tracing. No two tools appear to do the same thing.

    Naming Consistency5/5

    All seven tools use the same snake_case, emu_-prefixed convention with imperative verb forms (emu_load, emu_run, emu_trace, emu_read_mem). The pattern is predictable throughout, and the read/write pair is symmetric.

    Tool Count5/5

    Seven tools is a tight, well-scoped set for binary emulation: session setup, execution, introspection, and stubbing. Every tool has an evident role and none feels redundant or tacked on.

    Completeness4/5

    Load/reset/run/trace/read/write/hook covers the core emulate-and-inspect workflow, including memory inputs and call stubbing. Minor gaps remain: no register write or single-step/breakpoint tool, which could limit fine-grained experimentation, though memory writes and hooks partially work around this.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLMs to autonomously reverse engineer binaries using Ghidra's capabilities including decompilation, function analysis, automatic renaming, and BSim integration for function similarity matching.
      1
      AGPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to locally analyze and reverse engineer binaries through a compact 12-tool MCP interface for triage, function discovery, disassembly/decompilation, cross-references, strings/imports, call graphs, memory reads, annotations, and binary diffs.
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to run read-only static reverse-engineering tasks — binary triage, symbol and import inventory, per-function decompilation, and Android native-lib analysis — with untrusted samples confined to a no-network bubblewrap chamber that never executes the target.
      7
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to import, disassemble, and debug binaries directly so they can perform cross-reference reasoning, rename stripped functions, and recover structure layouts during native reverse-engineering workflows. It integrates with offline ELF reconnaissance output to support symbol and struct recovery without opening the Ghidra GUI.
      -