MCPEmulate

This project was vibecoded.

An MCP server that exposes CPU emulation, disassembly, and assembly as tools for LLM agents. Built on Unicorn (emulation), Capstone (disassembly), Keystone (assembly), and LIEF (binary parsing).

Agents can create isolated emulation sessions, load code or full executables, set breakpoints, hook syscalls, step through instructions, inspect memory and registers, and diff execution traces -- all through the standard MCP tool interface.

Supported Architectures

RISC-V architectures lack a Keystone backend, so the assemble tool returns an error for them. Disassembly and emulation work normally.

Setup

Requires Python 3.10+. Install with uv:

uv venv .venv
uv pip install -e ".[dev]"

Usage

Claude Desktop / MCP Client

Add to your MCP client configuration:

{
  "mcpServers": {
    "mcp-emulate": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/MCPEmulate", "mcp-emulate"]
    }
  }
}

CLI

# Default: stdio transport (for MCP clients)
mcp-emulate

# SSE transport (network, for web-based clients)
mcp-emulate --transport sse

# Streamable HTTP transport (newer MCP protocol)
mcp-emulate --transport streamable-http

Tools (41)

Session Management

Memory

Registers

Execution

Breakpoint Conditions

Conditional breakpoints accept expressions like:

eax == 42
rax > 0x1000 and rcx != 0
r0 == 0 or r1 & 0xff

Supported operators: ==, !=, >, <, >=, <=, &. Connectives: and, or.

Syscall Hooking

Each logged entry includes the syscall number, argument register values, and PC. The hook is architecture-aware -- it intercepts int 0x80 on x86_32, syscall on x86_64, svc 0 on ARM/AArch64, syscall on MIPS, and ecall on RISC-V.

Watchpoints

Tracing

Trace diff reports the common prefix length, the divergence point, and up to 50 differing entries with full disassembly.

Symbols

Symbols are used to annotate stack entries, trace output, memory maps, and step results.

Loading

load_executable uses LIEF for format detection. It maps each loadable segment with the correct permissions, sets PC to the entry point, and registers exported symbols automatically.

Example Workflow

A typical agent interaction:

1. create_emulator(arch="x86_64") -- start a session

2. assemble(arch="x86_64", code="mov rax, 60; syscall") -- assemble exit syscall

3. load_binary(session_id=..., data=..., address=0x1000, entry_point=0x1000) -- load code

4. hook_syscall(session_id=..., mode="stop") -- intercept syscalls

5. enable_trace(session_id=...) -- start recording

6. emulate(session_id=..., address=0x1000, count=100) -- run

7. get_trace(session_id=...) -- inspect what executed

8. get_syscall_log(session_id=...) -- see what syscalls were attempted

9. export_session(session_id=...) -- save state for later

Architecture

src/mcp_emulate/
  architectures.py   Architecture configs, register maps, syscall conventions
  session.py         EmulationSession (Unicorn wrapper), SessionManager
  server.py          41 MCP tool handlers via FastMCP

tests/
  test_emulate.py              132 pytest unit tests
  test_server_integration.py   112 checks over JSON-RPC (23 phases)

Key Design Decisions

• EmulationSession uses __slots__ for memory efficiency and to catch typos. Every new attribute must be declared.

• Breakpoints are dict[int, str | None] (address to optional condition), not a set. This supports conditional breakpoints while keeping the same lookup semantics.

• Syscall conventions are data, not code. A frozen dataclass per architecture describes the hook type, interrupt number filter, register names for nr/args/return. The hooking logic is generic.

• ks_arch/ks_mode are Optional on ArchConfig so architectures without Keystone (RISC-V) can exist without a dummy value. The assemble tool checks this and returns a clear error.

• load_executable writes via uc.mem_write() directly, bypassing the permission check on write_memory. This is intentional -- binary loaders need to populate read-only segments.

• Session serialization is versioned ("version": 1) for forward compatibility.

Tests

# Unit tests (132 tests, ~1s)
uv run pytest tests/test_emulate.py -v

# Integration tests (112 checks over JSON-RPC subprocess, ~30s)
uv run python tests/test_server_integration.py

# Both
uv run pytest tests/ -v && uv run python tests/test_server_integration.py

Dependencies

License

GPL-2.0-only