# x64dbg MCP Server

A production-level [Model Context Protocol](https://modelcontextprotocol.io) 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

```bash
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:

```powershell
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

```bash
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:

```bash
x64dbg-mcp setup
x64dbg-mcp doctor
x64dbg-mcp
```

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

```bash
x64dbg-mcp install-plugin
```

### Source checkout

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

```bash
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.

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

To run HTTP mode from a source checkout:

```powershell
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`.

```powershell
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.

```env
# 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:

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

If you are using a source checkout instead:

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

#### Windsurf / Cascade

```json
{
  "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:

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

If you are running from a source checkout:

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

Then connect your AI tool to this MCP endpoint:

```text
http://localhost:3000/mcp
```

Below are direct configuration examples for common AI tools.

#### Claude Code

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

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

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

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

#### Windsurf / Cascade

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

```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

```text
┌─────────────────┐  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:

```bash
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:

```bash
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:

```powershell
$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

```text
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](CONTRIBUTING.md)
- Security policy: see [SECURITY.md](SECURITY.md)
- Code of conduct: see [CODE_OF_CONDUCT.md](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.