emu-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@emu-mcp load tests/sample_x64 and emulate the function at 0x4011d0 with args 5 and 7"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
emu-mcp
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-mcpFrom GitHub
pip install git+https://github.com/RivaExits0/emu-mcp.gitFrom Source
git clone https://github.com/RivaExits0/emu-mcp.git
cd emu-mcp
pip install -e .[dev] # or just `pip install -e .` for productionSystem requirements (Linux):
gcc-x86-64-linux-gnuandbinutilsfor building test binaries. On Windows, cross-compilation is not required for the test suite.
Run
emu-mcp
# or
python -m emu_mcpThe 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-mcpshould 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 |
| Parse a binary and map its segments into Unicorn memory. | First, before any emulation. |
| Emulate one function, return value + registers. | After |
| Trace addresses and memory access (paginated). | After |
`emu_read_mem(addr, length, fmt="hex" | "ascii")` | Read up to 4096 bytes from emulated memory. |
| Write hex data to emulated memory. | To set up inputs before |
| Stub a call (malloc, strlen, …) with a fixed return value. | To avoid calling unsupported libc functions. |
| 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
0x4011d8Supported 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.pyRuns 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 demoExpected output:
=== Demo 1: add(5, 7) ===
result=12 stop=returned insns=11
...
ALL DEMO CHECKS PASSEDArchitecture
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/OPagination (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_resetclears 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.
🔗 Related Projects
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.0License
MIT — see LICENSE.
Available Tools
7 toolsemu_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
Scored across 7 tools
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.
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.
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.
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
Related MCP Connectors
Formally-verified injection/exfiltration detector for AI agents (MCP-02).
Jailbreak-proof AI guardrails. Automated Reasoning SMT solver, not an LLM. ZK proofs included.
Policy-aware AI execution, verification, cost, and trajectory evidence for agents.
Autonomous agent guardrails, bash sandboxing, MCP rugpull diffing & prompt firewalls.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables LLMs to autonomously reverse engineer binaries using Ghidra's capabilities including decompilation, function analysis, automatic renaming, and BSim integration for function similarity matching.1AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables 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.1MIT
- AlicenseAqualityBmaintenanceEnables 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.7MIT
- FlicenseNot gradedqualityAmaintenanceEnables 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.-