x64dbg MCP 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 multiple concurrent sessions — one MCP server can debug several programs in parallel

• 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 3602

The HTTP endpoint is fixed at http://localhost:3602/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:

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 3602

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=3602

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

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 3602

If you are running from a source checkout:

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

Then connect your AI tool to this MCP endpoint:

http://localhost:3602/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:3602/mcp"
    }
  }
}

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

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

Windsurf / Cascade

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

{
  "mcpServers": {
    "x64dbg-mcp": {
      "serverUrl": "http://localhost:3602/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.

Run as a Windows service

Register x64dbg-mcp as a Windows service that serves Streamable HTTP at a fixed endpoint, surviving reboots.

Service registration requires administrator privileges. Open PowerShell as Administrator before running these commands, or pass --elevate to trigger UAC.

# Install (default: 127.0.0.1:3602)
x64dbg-mcp service install

# Or with explicit values:
x64dbg-mcp service install --port 3602 --host 127.0.0.1

# Lifecycle
x64dbg-mcp service start
x64dbg-mcp service status
x64dbg-mcp service stop
x64dbg-mcp service restart
x64dbg-mcp service uninstall

# Run from a non-admin shell (UAC prompt will appear)
x64dbg-mcp service install --elevate

The service runs as LocalSystem and listens on http://<host>:<port>/mcp. Configuration lives at %ProgramData%\x64dbg-mcp\.env; edit it and run service restart to apply changes (e.g., X64DBG_PATH, MAX_SESSIONS).

Logs are at %ProgramData%\x64dbg-mcp\logs\:

• x64dbg-mcp.out.log — stdout

• x64dbg-mcp.err.log — stderr

• x64dbg-mcp.wrapper.log — daemon wrapper diagnostics

Note: under LocalSystem, x64dbg's GUI launches in Session 0 and is not visible on the user desktop. AI tool calls through the MCP work normally. If you need a visible x64dbg UI, run x64dbg-mcp in foreground HTTP mode instead of as a service.

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:

Capabilities

The server exposes 42 tools across four practical groups.

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 #A    │
│  (Claude, etc.) │                   │  (Node.js / TS)  │  per-session port │  + Bridge    │
└─────────────────┘                   │                  │ ◄───────────────► ├──────────────┤
                                      │  BridgeRegistry  │                   │ x64dbg #B    │
                                      │  (one client     │ ◄───────────────► ├──────────────┤
                                      │   per session)   │                   │ x64dbg #C    │
                                      └──────────────────┘                   └──────────────┘

At a high level, the MCP server speaks STDIO or Streamable HTTP to an AI client. Each load_executable or attach_to_process call spawns a fresh x64dbg instance on its own randomly allocated TCP port and creates an independent BridgeClient. The BridgeRegistry routes every tool call to the correct instance using the sessionId returned at load time. Multiple sessions can run in parallel up to MAX_SESSIONS (default 5). The plugin side is a lightweight C loader plus Python bridge that translates 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

# Integration test (requires x64dbg + MSVC-built fixtures)
npm run build:fixtures
npm run test:integration

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              # Per-session TCP client for the x64dbg bridge
│   ├── bridgeRegistry.ts      # Registry of active BridgeClient instances keyed by sessionId
│   ├── launcher.ts            # PE detection, port allocation, 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
│   ├── integration/
│   │   └── multi-session.test.ts  # Two-session Winsock integration test
│   ├── fixtures/                  # Winsock HTTP server/client PEs (build with npm run build:fixtures)
│   └── 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.