X64dbg Server

A production-level Model Context Protocol server that exposes x64dbg reverse-engineering and debugging capabilities to AI assistants over STDIO or Streamable HTTP.

It is designed for practical debugger automation, not just toy examples:

• Auto-detects PE architecture and launches x32dbg or x64dbg as needed
• Supports both load_executable and attach_to_process
• Exposes debugging, memory, analysis, and security triage tools through MCP
• Uses a lightweight bridge plugin and talks to x64bridge.dll directly via ctypes
• Does not depend on x64dbgpy

Quick Start

Recommended path

npm install -g x64dbg-mcp
x64dbg-mcp setup
x64dbg-mcp doctor

After that, choose one transport:

• STDIO: let your MCP host launch x64dbg-mcp directly
• Streamable HTTP: start a long-running server with:

x64dbg-mcp --transport streamable-http --host localhost --port 3000

The HTTP endpoint is fixed at http://localhost:3000/mcp.

stdio and streamable-http are the supported startup transports. The SDK still ships a standalone SSE server transport, but it is deprecated and this project does not expose it as a separate mode.

Requirements

• Windows only, because x64dbg is Windows-only
• Node.js 20+
• Python 3.10+
• CMake 3.15+ plus MSVC or MinGW only if you need to build the C loader from source

npm install downloads x64dbg automatically if it is not already available. The iced_x86 Python package is also installed automatically into detected Python environments; if that installation fails, the bridge falls back to x64dbg's own disassembly APIs.

Installation

Global npm install

npm install -g x64dbg-mcp

The global install path is the simplest one. Its postinstall step handles the usual setup work:

Step	What happens
x64dbg	Downloads the latest snapshot if not found locally
Plugin files	Deploys the loader and Python bridge files into the x64dbg plugins directories
Bridge auth	Generates BRIDGE_AUTH_TOKEN and writes x64dbg_mcp_bridge.token
Python	Detects Python install paths and records PYTHON_HOME_X64 / PYTHON_HOME_X86
iced_x86	Installs it into detected Python environments if needed
.env	Creates a config file with detected values and defaults

Before continuing, review the configuration values in the next section if your x64dbg install path, Python install path, or HTTP port should differ from the detected defaults.

Then run:

x64dbg-mcp setup
x64dbg-mcp doctor
x64dbg-mcp

If you need to rebuild and redeploy the loader manually, use:

x64dbg-mcp install-plugin

Source checkout

Use this path if you are developing on the project itself:

git clone https://github.com/ouonet/x64dbg-mcp.git
cd x64dbg-mcp
npm install
npm run build

Then review the configuration section below, especially if X64DBG_PATH, Python paths, or the default HTTP port need to change.

npm run setup
npm run install-plugin
npm run doctor
npm start

To run HTTP mode from a source checkout:

node .\dist\server.js --transport streamable-http --host localhost --port 3000

If you want the x64dbg-mcp command in a source checkout too, run npm link after npm run build.

If x64dbg already exists in a non-default location, set X64DBG_PATH in .env before npm run install-plugin.

Manual plugin installation

Most users should not need this. Use it only if you want to build and copy the loader manually instead of running install-plugin.

cd plugin\loader

# 64-bit
cmake -B build64 -A x64
cmake --build build64 --config Release
$p64 = "C:\x64dbg\release\x64\plugins"
Copy-Item build64\Release\x64dbg_mcp_loader.dp64 $p64
Copy-Item ..\x64dbg_mcp_bridge.py                $p64
Copy-Item ..\x64dbg_bridge_sdk.py                $p64

# 32-bit
cmake -B build32 -A Win32 -DBUILD_32BIT=ON
cmake --build build32 --config Release
$p32 = "C:\x64dbg\release\x32\plugins"
Copy-Item build32\Release\x64dbg_mcp_loader.dp32 $p32
Copy-Item ..\x64dbg_mcp_bridge.py                $p32
Copy-Item ..\x64dbg_bridge_sdk.py                $p32

npm run install-plugin performs the same work for both architectures by default. Pass -No32 if you want to skip the 32-bit build.

Configuration

npm install creates .env automatically. Edit that file directly, or run setup again if you want the interactive flow.

# x64dbg path (auto-detected)
X64DBG_PATH=C:\x64dbg

# Python install directories used by the C loader
PYTHON_HOME_X64=C:\Python314
PYTHON_HOME_X86=C:\Python312-32

# Bridge
BRIDGE_HOST=127.0.0.1
BRIDGE_PORT=27042
BRIDGE_AUTH_TOKEN=<auto-generated>

# MCP transport defaults
MCP_TRANSPORT=stdio
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=3000

# Logging / limits
LOG_LEVEL=info
MAX_SESSIONS=1
SESSION_TIMEOUT_MS=3600000

Variable	Default	Description
X64DBG_PATH	auto-detected	x64dbg installation directory
PYTHON_HOME_X64	auto-detected	Preferred Python 64-bit install directory
PYTHON_HOME_X86	auto-detected	Preferred Python 32-bit install directory
BRIDGE_HOST	127.0.0.1	TCP host for the local bridge
BRIDGE_PORT	27042	TCP port for the local bridge
BRIDGE_AUTH_TOKEN	auto-generated	Shared secret for MCP to bridge requests
MCP_TRANSPORT	stdio	Default startup transport: stdio or streamable-http
MCP_HTTP_HOST	127.0.0.1	Default HTTP bind host
MCP_HTTP_PORT	3000	Default HTTP listen port
LOG_LEVEL	info	error, warn, info, or debug
MAX_SESSIONS	1	Active session limit for the current bridge architecture
SESSION_TIMEOUT_MS	3600000	Idle session timeout in milliseconds

If you manually start x64dbg outside the MCP flow, keep the deployed x64dbg_mcp_bridge.token file in the plugins directory so the bridge enforces the same token as the MCP server.

Use With Your MCP Host

Note: You do not need to pre-launch x64dbg manually. The MCP server auto-launches the correct debugger when you call load_executable or attach_to_process.

STDIO host configuration

Use STDIO when your MCP host can spawn a local process.

Claude Desktop

If you installed the package globally:

{
  "mcpServers": {
    "x64dbg-mcp": {
      "command": "x64dbg-mcp"
    }
  }
}

If you are using a source checkout instead:

{
  "mcpServers": {
    "x64dbg-mcp": {
      "command": "node",
      "args": ["C:\\path\\to\\x64dbg-mcp\\dist\\server.js"]
    }
  }
}

Windsurf / Cascade

{
  "mcpServers": {
    "x64dbg-mcp": {
      "command": "node",
      "args": ["C:\\path\\to\\x64dbg-mcp\\dist\\server.js"],
      "env": { "BRIDGE_PORT": "27042" }
    }
  }
}

Streamable HTTP

Use Streamable HTTP when you want to start x64dbg-mcp once and let an AI tool connect to it through a fixed local URL.

Start the server first.

If you installed the package globally:

x64dbg-mcp --transport streamable-http --host localhost --port 3000

If you are running from a source checkout:

node .\dist\server.js --transport streamable-http --host localhost --port 3000

Then connect your AI tool to this MCP endpoint:

http://localhost:3000/mcp

Below are direct configuration examples for common AI tools.

Claude Code

Create a .mcp.json file in the project root:

{
  "mcpServers": {
    "x64dbg-mcp": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Or add the same server to Claude Code with its CLI:

claude mcp add --transport http x64dbg-mcp http://localhost:3000/mcp

Windsurf / Cascade

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "x64dbg-mcp": {
      "serverUrl": "http://localhost:3000/mcp"
    }
  }
}

If you already have other MCP servers configured in that file, just add the x64dbg-mcp entry under mcpServers.

If your AI tool does not support remote HTTP MCP servers and only knows how to launch a local command, use the STDIO setup above instead.

CLI flags override MCP_TRANSPORT, MCP_HTTP_HOST, and MCP_HTTP_PORT from the environment. The legacy MCP_TRANSPORT=http alias is still accepted for compatibility.

Typical Prompts

These are good examples of the kinds of requests the MCP server is built to support:

• "Load C:\samples\target.exe and analyze it for suspicious behavior"
• "Attach to PID 1234 and inspect the current thread"
• "Find the license check function"
• "Generate a first-pass malware triage report"

Typical tool flows behind those prompts look like this:

Goal	Typical tools
Load and debug a binary	load_executable, get_status, continue_execution, wait_for_state, disassemble
Attach to a live process	attach_to_process, get_status, pause_execution, get_call_stack, get_registers, detach_session
Malware triage	generate_security_report, analyze_suspicious_apis, detect_anti_debug, find_strings
Reverse engineering	find_strings, get_cross_references, analyze_function, collect_bp_args

Capabilities

The server exposes 38 tools across four practical groups.

Group	Scope
Core debugging	load or attach, control execution, manage breakpoints, inspect session state
Memory and registers	read and write memory, inspect registers, switch threads, walk call stacks
Analysis	disassembly, function analysis, cross references, modules, imports, exports, strings, traces
Security triage	packing checks, suspicious APIs, anti-debug detection, section anomalies, consolidated reports

Representative tools include load_executable, attach_to_process, get_status, read_memory, disassemble, analyze_function, and generate_security_report.

Architecture

┌─────────────────┐  STDIO / HTTP     ┌──────────────────┐  TCP (JSON)  ┌──────────────┐
│  AI Assistant   │ ◄───────────────► │  MCP Server      │ ◄──────────► │  x64dbg      │
│  (Claude, etc.) │                   │  (Node.js / TS)  │  port 27042  │  + Bridge    │
└─────────────────┘                   └──────────────────┘              │    Plugin    │
                                                                        └──────────────┘

At a high level, the MCP server in src/ speaks STDIO or Streamable HTTP to an AI client, then forwards requests over a local TCP bridge to the plugin running inside x64dbg. The plugin side is a lightweight C loader plus Python bridge that translates those requests into x64dbg Bridge SDK calls.

Development And Testing

Development commands:

npm run ci
npm run ci -- --no-loader
npm run dev
npm run sync-plugin
npm run setup-x64dbg
npm run setup-x64dbg -- --force
npm run build
npm run lint
npm run clean

Testing commands:

npm test
python plugin/tests/test_bridge.py
npm run test:e2e
npm run test:http-smoke
npm run doctor

npm run dev automatically syncs Python files into the bundled x64dbg checkout before starting the server.

npm run inspector launches MCP Inspector. On first run it downloads @modelcontextprotocol/inspector via npx, so restricted environments may need HTTP_PROXY / HTTPS_PROXY or a global install.

Reusable verifier scripts live under test/e2e/. They require an explicit target:

• TARGET_EXE=C:\path\to\sample.exe for load-based verification
• TARGET_PID=1234 or TARGET_PROCESS_NAME=notepad for attach-based verification

Examples:

$env:TARGET_EXE = "C:\Windows\System32\notepad.exe"
node test/e2e/verify_breakpoint_chain.mjs

$env:TARGET_PROCESS_NAME = "notepad"
node test/e2e/verify_attach_chain.mjs

CI in .github/workflows/ci.yml runs TypeScript, Python, and loader-build jobs on every push. On tagged releases (v*), it also publishes the npm package with the prebuilt loader binaries included.

Project Structure

x64dbg-mcp/
├── src/
│   ├── server.ts              # Entry point and transport bootstrap
│   ├── cli.ts                 # CLI parsing for transport/host/port
│   ├── httpServer.ts          # Streamable HTTP server and MCP session handling
│   ├── mcpServer.ts           # Shared MCP server factory and tool registration
│   ├── bridge.ts              # TCP client for the x64dbg bridge
│   ├── launcher.ts            # PE detection and debugger startup
│   ├── session.ts             # Session lifecycle and garbage collection
│   ├── config.ts              # Env-backed configuration loading
│   ├── errors.ts              # Shared error helpers
│   ├── logger.ts              # Winston logger
│   ├── types.ts               # Shared TypeScript types
│   └── tools/
│       ├── debug.ts
│       ├── memory.ts
│       ├── analysis.ts
│       ├── security.ts
│       └── index.ts
├── plugin/
│   ├── x64dbg_mcp_bridge.py   # Python bridge running inside x64dbg
│   ├── x64dbg_bridge_sdk.py   # ctypes wrapper for x64bridge.dll
│   ├── loader/
│   │   ├── x64dbg_mcp_loader.c
│   │   ├── CMakeLists.txt
│   │   └── prebuilt/
│   ├── tests/
│   │   └── test_bridge.py
│   └── README.md
├── scripts/
│   ├── setup.mjs
│   ├── doctor.mjs
│   ├── install-plugin.mjs
│   ├── install-plugin.ps1
│   ├── postinstall.mjs
│   ├── prepack.mjs
│   ├── setup-x64dbg.mjs
│   ├── sync-plugin.mjs
│   ├── ci.mjs
│   └── manual/
├── test/
│   ├── basic.test.ts
│   └── e2e/
├── x64dbg/                    # Bundled x64dbg snapshot used in development/tests
├── package.json
├── .env.example
└── README.md

License

MIT

Community

• Contribution guide: see CONTRIBUTING.md
• Security policy: see SECURITY.md
• Code of conduct: see CODE_OF_CONDUCT.md
• Bug reports and feature requests: use the GitHub templates under .github/ISSUE_TEMPLATE/

For non-sensitive questions or usage issues, open a GitHub issue. For vulnerabilities, follow the private reporting process in SECURITY.md instead of opening a public issue.