Overview

x64dbg-mcp

Production-grade Model Context Protocol server and native bridge plugin for the x64dbg Windows debugger.

234

Verified MCP Tools

31

Functional Domains

Named Pipe

Win32 Local IPC

/W4 /WX

Strict Zero Warnings

x64dbg-mcp bridges local AI coding agents and autonomous pair programmers (including Google Gemini Antigravity, Anthropic Claude Desktop, Cursor, and Windsurf) with the x64dbg debugger core on Windows. It empowers agents to inspect memory, set hardware breakpoints, unwind call stacks, automate console targets, and analyze offline execution records via standard MCP JSON-RPC protocols.

Standardized FastMCP Protocol

Every tool call is strictly validated with type annotations, parameter schemas, and error boundaries, eliminating silent failures or corrupted debugger state.

Key Architectural Features

Unlike basic scripting wrappers, x64dbg-mcp is structured in two dedicated layers:

In-Process C++ Plugin (.dp64): Hosts a dedicated multithreaded Win32 named pipe listener inside the 64-bit debugger process, accessing x64dbg's native Bridge SDK with sub-millisecond dispatch times.
FastMCP Python Adapter: Speaks standard JSON-RPC over Stdio with AI client processes and handles session serialization across \\.\pipe\x64dbg_mcp.
Bi-directional Console Interaction: Injects keystrokes using WriteConsoleInputW and captures screen buffer slices via ReadConsoleOutputCharacterW for interactive CLI targets.
Offline Binary Trace Inspector: High-speed binary parser capable of reading .trace32 and .trace64 archives without launching x64dbg.

Deployment

Quick Start Guide

Deploy pre-built release binaries and attach your AI agent in under two minutes.

1

Clone & Install Python Server

Ensure Python 3.10+ is installed on your Windows machine:

PowerShell

git clone https://github.com/cipherwire/x64dbg-mcp.git
cd x64dbg-mcp
pip install -r requirements.txt
pip install -e .

2

Deploy Native Plugin

Download x64dbg_mcp.dp64 from the GitHub Releases page and place it inside your 64-bit x64dbg plugins folder:

Target Path

C:\path\to\x64dbg\release\x64\plugins\x64dbg_mcp.dp64

3

Launch and Verify Listener

Start x64dbg.exe (64-bit). Inspect the Log tab in the debugger to verify the named pipe listener is active:

x64dbg Console Log

[x64dbg-MCP] Plugin loaded successfully
[x64dbg-MCP] Named pipe server listening on \\.\pipe\x64dbg_mcp

Internals

Architecture & IPC Design

Two-tier separation of concerns: low-overhead C++ native execution inside the debuggee host, coupled with Python FastMCP over standard I/O.

Topology

+-------------------------------------------------------------+
|              AI Environment (Antigravity / Claude / Cursor) |
+-------------------------------------------------------------+
                               |
                        MCP JSON-RPC (Stdio)
                               |
+-------------------------------------------------------------+
|                   FastMCP Python Server                     |
|                 (mcp_server / 234 Tools)                    |
+-------------------------------------------------------------+
                               |
                     Win32 Named Pipe IPC
                    \\.\pipe\x64dbg_mcp
                               |
+-------------------------------------------------------------+
|                Native C++ Plugin (x64dbg_mcp.dp64)          |
|                 (MSVC /W4 /WX Strict Build)                 |
+-------------------------------------------------------------+
                               |
                     Direct Bridge SDK Calls
                               |
+-------------------------------------------------------------+
|                    x64dbg Debugger Core                     |
+-------------------------------------------------------------+

IPC Message Framing

The native server thread operates in message byte-stream mode. Messages sent across \\.\pipe\x64dbg_mcp are single-line JSON commands terminated by a newline (\n):

JSON Wire Format

// FastMCP to Plugin
{"cmd": "get_registers"}

// Plugin to FastMCP
{"success": true, "data": {"rax": "0x00007FF7F72F1125", "rip": "0x00007FF7F72F1125", ...}}

Integration

Client Configurations

Copy-paste configuration blocks for leading AI agents and IDEs.

Add to %USERPROFILE%\.gemini\config\mcp_config.json:

mcp_config.json

{
  "mcpServers": {
    "x64dbg": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "C:\\path\\to\\x64dbg-mcp"
    }
  }
}

Add to %APPDATA%\Claude\claude_desktop_config.json:

claude_desktop_config.json

{
  "mcpServers": {
    "x64dbg": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "C:\\path\\to\\x64dbg-mcp"
    }
  }
}

Add to project .cursor/mcp.json or configure under Settings -> Features -> MCP:

.cursor/mcp.json

{
  "mcpServers": {
    "x64dbg": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "C:\\path\\to\\x64dbg-mcp"
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

mcp_config.json

{
  "mcpServers": {
    "x64dbg": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "C:\\path\\to\\x64dbg-mcp"
    }
  }
}

Configure in Cline extension settings JSON:

cline_mcp_settings.json

{
  "mcpServers": {
    "x64dbg": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "C:\\path\\to\\x64dbg-mcp"
    }
  }
}

API Reference

Interactive Tool Explorer

Search, filter, and inspect all 234 debugging tools across 15 domains.

Interactive Targets

Bi-directional Console I/O

Control CLI targets and CrackMes without mutating Windows standard console handles.

Many Windows CLI targets check console handles directly with GetFileType or read characters via ReadConsoleInputW. When debuggers redirect standard handles over basic pipes, these programs crash or detect the debugger. x64dbg-mcp solves this by injecting hardware keystrokes and reading screen buffer cells directly:

send_console_input(text, append_enter) Console & Process I/O

Uses WriteConsoleInputW to simulate hardware keydown/keyup events directly in the target process console buffer.

read_console_output(lines) Console & Process I/O

Queries screen coordinates using ReadConsoleOutputCharacterW without pausing the target or mutating console scrollback state.

Offline Analysis

Offline Trace File Inspector

Backtrack execution and inspect registers from .trace32 and .trace64 recordings without running x64dbg.

Python SDK

from mcp_server.trace_reader import TraceReader

reader = TraceReader("session.trace64")
print(f"Total instructions captured: {reader.instruction_count}")

# Query memory writes to target buffer
hits = reader.find_memory_writes(address=0x00405020, size=16)
for hit in hits:
    print(f"IP: {hex(hit.ip)} wrote to buffer at step #{hit.step_index}")

Build Systems

Building from Source

Compile the native C++ plugin using MSVC with strict zero-warning policy.

Developer PowerShell

# Automatic compilation and deployment:
powershell -ExecutionPolicy Bypass -File .\scripts\build.ps1 -Deploy

The build script enforces strict flags: /W4 /WX /O2 /std:c++17 /DUNICODE /D_UNICODE. Any compiler warning is treated as a fatal build failure.

Safety Model

Security & Boundaries

Process isolation, privilege boundaries, and local named pipe transport.

The Win32 named pipe \\.\pipe\x64dbg_mcp communicates strictly over local inter-process boundaries. It does not bind network ports, requires local user session credentials, and enforces message boundary limits to avoid buffer overflow risks.