/x64dbg-mcp-server

x64dbg Reverse Engineering — MCP Workflow Guide

You are controlling x64dbg through MCP tools.

**Transport matters:**

• **SSE clients** receive push notifications for debugger events (breakpoints, exceptions, state changes) in real time.
• **HTTP clients** must poll — call `WaitForEvent` to long-poll for events, or read the `[state]` and `[event:*]` lines included in every tool response.

Treat every assumption about debugger state as stale until verified by a tool response.

---

Rule 1: Always Know Your State

**Before every action**, call `GetDebugState`. No exceptions.

• `NO_TARGET` — nothing loaded. Use `LoadBinary` or `AttachProcess` first.
• `PAUSED` — target is stopped. You can read memory, disassemble, inspect registers.
• `RUNNING` — target is executing. You CANNOT read memory, disassemble, or inspect anything. Call `WaitForPause` or `PauseDebug` first.

Every tool response includes a `[state]` line at the end showing the current debugger status — PAUSED with address/module/instruction, RUNNING, or NO_TARGET. Always read it. This is your primary state awareness mechanism.

Every tool response may also include `[event:*]` lines — queued debugger events (breakpoints hit, exceptions, DLL loads) that occurred since your last call. Always read these too.

If the user says "paused", "hit breakpoint", "stopped", or "debugger is paused" — immediately call `GetDebugState` to see where you are. Do not guess.

---

Rule 2: Never Assume State Between Calls

MCP is request/response. Between your tool calls, anything can happen — breakpoints can hit, exceptions can fire, the user can interact with the debugger. Every time you are about to act, verify first.

Bad:

SetBreakpoint → run → Disassemble  (wrong: run blocks but verify anyway)

Good:

GetDebugState → SetBreakpoint → run → GetDebugState → Disassemble

---

Rule 3: Core Workflows

Load and analyze a binary

GetDebugState
LoadBinary (path)
WaitForPause            — target pauses at system breakpoint
GetDebugState           — confirm PAUSED, note the address
GetAllRegisters         — see initial state
ListModules             — see what's loaded
Disassemble             — look at current code

Set breakpoint and run to it

GetDebugState           — must be PAUSED
SetBreakpoint (target)  — set the BP
run                     — blocks until target pauses (5-min timeout)
GetDebugState           — confirm PAUSED, check address
Disassemble             — see where we landed
GetAllRegisters         — inspect state

Step through code

GetDebugState           — must be PAUSED
StepOver                — response includes new address + disassembly
                        — read the response carefully before next step
StepOver                — keep stepping, reading each response
GetAllRegisters         — check registers when needed
GetCallStack            — check call context when needed

Find and hook an API call

SearchSymbols (pattern) — find the API across all modules
SetBreakpoint (address) — break on it
run                     — blocks until BP hits
GetDebugState
GetArguments            — read function arguments
GetCallStack            — see who called it

Trace execution

GetDebugState           — must be PAUSED
TraceInto (count)       — step N instructions, get address + disasm log
GetDebugState           — see where we ended up

Unpack a binary

LoadBinary → WaitForPause → GetDebugState
AnalyzeModule           — check sections, EP, image size
DetectOEP               — look for packing indicators (RWX sections, zero raw sizes)
SetHardwareBreakpoint   — on suspected OEP or after unpacking stub
run → GetDebugState     — run blocks until pause
DumpModule              — dump the unpacked module

Patch memory

GetDebugState           — must be PAUSED
Disassemble (address)   — see current bytes
WriteMemToAddress       — patch with new bytes
Disassemble (address)   — verify the patch
GetPatches              — see all active patches

Monitor while user interacts with GUI (HTTP only)

WaitForEvent (timeoutMs: 120000)  — long-poll up to 2 minutes
                                  — returns any events that fired
GetDebugState                     — check where we are now
WaitForEvent (timeoutMs: 120000)  — keep watching

---

Rule 4: All 84 Tools Reference

Every tool response includes a `[state]` line showing current debugger status and any `[event:*]` lines with queued events. You always know where you are.

State & Control (always available)

| Tool | Parameters | Description | |------|-----------|-------------| | `GetDebugState` | — | Current state (NO_TARGET/RUNNING/PAUSED), PID, address, module | | `LoadBinary` | `filePath` | Load an executable into the debugger | | `AttachProcess` | `pid` | Attach to a running process by PID | | `run` | `timeoutMs?` (default 300000) | Resume execution (F9). Blocks until target pauses or timeout | | `PauseDebug` | — | Pause the target (F12) | | `WaitForPause` | `timeout?` (ms, default 10000) | Block until target pauses (breakpoint/exception) | | `StopDebug` | — | Terminate debug session | | `RestartDebug` | — | Restart debug session | | `ExecuteDebuggerCommand` | `command` | Run any x64dbg command string. Blocks if target becomes RUNNING | | `EvalExpression` | `expression` | Evaluate expression (address, register, symbol, arithmetic) | | `Echo` | `message` | Echo input back (connectivity test) | | `ListCommandsByCategory` | `category?` | List available MCP tools | | `SearchForStrings` | `searchText` | Search process memory for text | | `GetEventLog` | `count?` (default 20) | Last N debugger events | | `ClearEventLog` | — | Clear the event log | | `WaitForEvent` | `timeoutMs?` (default 30000) | Long-poll for debugger events. For HTTP clients to watch state changes |

Stepping (requires PAUSED)

| Tool | Parameters | Description | |------|-----------|-------------| | `StepInto` | — | Single-step