hyperdbg-mcp

An MCP server that exposes HyperDbg

• the hypervisor-assisted, ring-0 debugger - to LLM agents.

Status: early development (v0.0.1). The design is documented in docs/DESIGN.md. End-to-end operation requires a Windows host with HyperDbg installed and its driver loaded; the FFI layer has not yet been validated against a live libhyperdbg.dll.

How it works

The server loads libhyperdbg.dll via ctypes (there is no HTTP API) and registers a set of MCP tools that map to HyperDbg's command surface. Command text output is captured through HyperDbg's message callback (see docs/DESIGN.md §2).

MCP client ──stdio──► hyperdbg-mcp (Python) ──ctypes──► libhyperdbg.dll ──► driver + VMM

Safety

HyperDbg operates at ring-0; a bad write can bugcheck the host, and memory/disassembly read back from the target may be adversarial (you may be debugging malware). The server therefore:

• annotates read-only vs destructive tools (ToolAnnotations);
• requires per-call confirmation (MCP elicitation) for destructive tools;
• supports a hard --read-only mode that does not register write/script tools at all;
• wraps all debuggee-sourced data in an untrusted-data envelope so it is treated as inert;
• writes an append-only audit log of every call.

# read-only, safest
hyperdbg-mcp --read-only

# full access (destructive tools gated behind confirmation)
hyperdbg-mcp --lib-path C:\path\to\libhyperdbg.dll --audit-log audit.jsonl

# mock backend - exercise the full tool surface with no HyperDbg / DLL
hyperdbg-mcp --mock

# Debugger Mode - connect to a remote debuggee over serial (halts it on connect)
hyperdbg-mcp --remote-com com4 --baudrate 115200

Modes. Default is local VMI (single machine, debug via the local hypervisor). Debugger Mode (--remote-com / --remote-pipe / --remote-net) connects to a separate debuggee machine and, by default, halts it on connect - which is what gives a valid CPU context for register/memory reads and stepping. (Register reads are not meaningful in local VMI mode with nothing paused.)

Tools

Read (always available): hd_mem_read, hd_reg_read_all, hd_reg_read, hd_eval, hd_disasm, hd_list_modules, hd_status. Execution control (available in --read-only): hd_exec_continue, hd_exec_pause, hd_exec_step. Target-mutating (full mode only, confirmation-gated): hd_exec_command, hd_bp_set, hd_mem_write, hd_reg_write, hd_script_run.

Development

pip install -e ".[dev]"
pytest
ruff check .

Roadmap

• Validate FFI against a live HyperDbg host.
• Streamable-HTTP transport + progress streaming for long Intel-PT / LBR traces.
• Symbol-aware helpers; richer structured outputs.

License

GPL-3.0-or-later, matching the HyperDbg project.