Skip to content
Back to search

x64dbg-mcp

MCP server plugin for x64dbg debugger - enables AI agents and external tools to control debugging via JSON-RPC 2.0 over HTTP/SSE

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/setsunayukiovo--x64dbg-mcp/badge.svg)](/listings/setsunayukiovo--x64dbg-mcp)

HTML

<a href="/listings/setsunayukiovo--x64dbg-mcp"><img src="/api/listings/setsunayukiovo--x64dbg-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Copy the compiled plugins to their respective debugger directories:

# For x64dbg (64-bit)
# Replace <x64dbg-path> with your actual x64dbg installation directory
copy dist\x64dbg_mcp.dp64 <x64dbg-path>\x64\plugins\

# For x32dbg (32-bit)
copy dist\x32dbg_mcp.dp32 <x64dbg-path>\x32\plugins\

# Example (if installed at C:\x64dbg):
# copy dist\x64dbg_mcp.dp64 C:\x64dbg\x64\plugins\
# copy dist\x32dbg_mcp.dp32 C:\x64dbg\x32\plugins\

2. (Optional) Copy the configuration file:

# For x64dbg
mkdir <x64dbg-path>\x64\plugins\x64dbg-mcp
copy config.json <x64dbg-path>\x64\plugins\x64dbg-mcp\

# For x32dbg
mkdir <x64dbg-path>\x32\plugins\x32dbg-mcp
copy config.json <x64dbg-path>\x32\plugins\x32dbg-mcp\

3. Restart x64dbg/x32dbg to load the plugin

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 522 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # x64dbg MCP Server Plugin
  2. English | [中文](docs/README_CN.md)
  3. A Model Context Protocol (MCP) server implementation for x64dbg and x32dbg, enabling remote debugging through a JSON-RPC 2.0 interface. This plugin allows external applications and AI agents to interact with the debugger programmatically.
  4. **Now supports both x64 and x86 architectures!**
  5. ## Features
  6. - **Full MCP Specification Compliance**: Implements all three core MCP building blocks
  7. - **Tools (79)**: AI-invokable debugging functions
  8. - **Resources (7 + 8 templates)**: Application-controlled context data sources
  9. - **Prompts (10)**: User-guided debugging workflow templates
  10. - **JSON-RPC 2.0 Protocol**: Standard, language-agnostic interface
  11. - **Streamable HTTP transport** (MCP 2025-03-26) on `/mcp`, plus legacy HTTP+SSE on `/sse` for older clients
  12. - **Tools - AI-Controlled Debugging (79 functions)**:
  13. - Execution control (init/run/pause/step/run_to/restart/stop)
  14. - Memory read/write/search/allocate
  15. - Register access (50+ registers including GPR, SSE, AVX)
  16. - Breakpoint management (software, hardware, memory, conditional, logging)
  17. - Disassembly and symbol resolution
  18. - Thread management (list, switch, suspend, resume)
  19. - Stack trace and analysis
  20. - **Dump & Analysis** (module dump, memory dump, packer detection, OEP detection)
  21. - **Script execution** (execute x64dbg/x32dbg commands, batch operations)
  22. - **Context snapshots** (capture and compare debugging state)
  23. - **Resources - Context Providers (7 direct + 8 templates)**:
  24. - Direct resources: debugger state, registers, modules, threads, memory map, breakpoints, stack
  25. - Resource templates: memory content, disassembly, module info, symbol resolution, function analysis
  26. - Read-only, application-controlled access
  27. - **Prompts - Workflow Templates (10 prompts)**:
  28. - Crash analysis, vulnerability hunting, function tracing
  29. - Binary unpacking, algorithm reversing, execution comparison
  30. - String hunting, code patching, API monitoring
  31. - Debug session initialization
  32. - **Security**: Permission-based access control
  33. - **Extensible**: Plugin architecture for custom methods, resources, and prompts
  34. ### Prerequisites
  35. - **Windows 10/11** (64-bit host; supports building both x64 and x86 plugins)
  36. - **CMake** 3.15 or higher
  37. - **Visual Studio 2022** with C++ Desktop Development workload
  38. - **vcpkg** - Package manager for C++ libraries
  39. - **Git** - For cloning the repository
  40. ### Quick Build
  41. The easiest way to build is using the provided build script:
  42. ```powershell
  43. # Clone the repository
  44. git clone https://github.com/SetsunaYukiOvO/x64dbg-mcp.git
  45. cd x64dbg-mcp
  46. # Build both x64 and x86 architectures (recommended)
  47. .\build.bat
  48. # Build only x64 architecture
  49. .\build.bat --x64-only
  50. # Build only x86 architecture
  51. .\build.bat --x86-only
  52. # Clean rebuild
  53. .\build.bat --clean
  54. # The script will:
  55. # 1. Automatically detect vcpkg installation
  56. # 2. Download dependencies (nlohmann_json)
  57. # 3. Configure CMake for both architectures
  58. # 4. Build using Visual Studio with parallel compilation
  59. # 5. Copy output files to dist/ directory
  60. ```
  61. Build script options:
  62. ```powershell
  63. .\build.bat # Build both x64 and x86 (Release)
  64. .\build.bat --clean # Clean rebuild both architectures
  65. .\build.bat --x64-only # Build x64 only
  66. .\build.bat --x86-only # Build x86 only
  67. .\build.bat --debug # Debug build (future support)
  68. ```
  69. **Output files** (in `dist/` directory):
  70. - x64 plugin: `dist\x64dbg_mcp.dp64` (~837 KB)
  71. - x86 plugin: `dist\x32dbg_mcp.dp32` (~800 KB)
  72. ### Manual Build Steps
  73. If you prefer manual control:
  74. 1. **Install vcpkg** (if not already installed):
  75. ```powershell
  76. git clone https://github.com/Microsoft/vcpkg.git C:\vcpkg
  77. C:\vcpkg\bootstrap-vcpkg.bat
  78. setx VCPKG_ROOT "C:\vcpkg"
  79. ```
  80. 2. **Clone the repository**:
  81. ```powershell
  82. git clone https://github.com/SetsunaYukiOvO/x64dbg-mcp.git
  83. cd x64dbg-mcp
  84. ```
  85. 3. **Configure with CMake**:
  86. ```powershell
  87. # For x64 build
  88. cmake -B build_x64 -G "Visual Studio 17 2022" -A x64 ^
  89. -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake ^
  90. -DVCPKG_TARGET_TRIPLET=x64-windows ^
  91. -DXDBG_ARCH=x64
  92. # For x86 build
  93. cmake -B build_x86 -G "Visual Studio 17 2022" -A Win32 ^
  94. -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake ^
  95. -DVCPKG_TARGET_TRIPLET=x86-windows ^
  96. -DXDBG_ARCH=x86
  97. ```
  98. 4. **Build**:
  99. ```powershell
  100. cmake --build build_x64 --config Release
  101. cmake --build build_x86 --config Release
  102. ```
  103. 5. **Output**:
  104. - x64 plugin: `build_x64\bin\Release\x64dbg_mcp.dp64`
  105. - x86 plugin: `build_x86\bin\Release\x32dbg_mcp.dp32`
  106. ## Installation
  107. 1. Copy the compiled plugins to their respective debugger directories:
  108. ```powershell
  109. # For x64dbg (64-bit)
  110. # Replace <x64dbg-path> with your actual x64dbg installation directory
  111. copy dist\x64dbg_mcp.dp64 <x64dbg-path>\x64\plugins\
  112. # For x32dbg (32-bit)
  113. copy dist\x32dbg_mcp.dp32 <x64dbg-path>\x32\plugins\
  114. # Example (if installed at C:\x64dbg):
  115. # copy dist\x64dbg_mcp.dp64 C:\x64dbg\x64\plugins\
  116. # copy dist\x32dbg_mcp.dp32 C:\x64dbg\x32\plugins\
  117. ```
  118. 2. (Optional) Copy the configuration file:
  119. ```powershell
  120. # For x64dbg
  121. mkdir <x64dbg-path>\x64\plugins\x64dbg-mcp
  122. copy config.json <x64dbg-path>\x64\plugins\x64dbg-mcp\
  123. # For x32dbg
  124. mkdir <x64dbg-path>\x32\plugins\x32dbg-mcp
  125. copy config.json <x64dbg-path>\x32\plugins\x32dbg-mcp\
  126. ```
  127. 3. Restart x64dbg/x32dbg to load the plugin
  128. ## Usage
  129. ### Starting the Server
  130. 1. Open x64dbg for a 64-bit target or x32dbg for a 32-bit target
  131. 2. Navigate to **Plugins → MCP Server → Start MCP HTTP Server**
  132. 3. The server will start on the configured port (default: 3000)
  133. 4. Access the server at `http://127.0.0.1:3000`
  134. ### Configuration
  135. Edit `config.json` to customize settings:
  136. ```json
  137. {
  138. "version": "1.0.12",
  139. "server": {
  140. "address": "127.0.0.1",
  141. "port": 3000
  142. },
  143. "permissions": {
  144. "allow_memory_write": false,
  145. "allow_register_write": false,
  146. "allow_script_execution": false,
  147. "allow_breakpoint_modification": true,
  148. "allowed_methods": ["debug.*", "memory.*"]
  149. },
  150. "security": {
  151. "origin_allowlist": [],
  152. "host_allowlist": [],
  153. "auth_enabled": false,
  154. "auth_token": ""
  155. },
  156. "logging": {
  157. "enabled": true,
  158. "level": "info",
  159. "file": "x64dbg_mcp.log",
  160. "max_file_size_mb": 10,
  161. "console_output": true
  162. },
  163. "timeout": {
  164. "request_timeout_ms": 30000,
  165. "step_timeout_ms": 10000,
  166. "memory_read_timeout_ms": 5000
  167. },
  168. "features": {
  169. "enable_notifications": true,
  170. "enable_heartbeat": true,
  171. "heartbeat_interval_seconds": 30,
  172. "enable_batch_requests": true,
  173. "auto_start_mcp_on_plugin_load": false
  174. }
  175. }
  176. ```
  177. #### Configuration editor
  178. Choose **Plugins > MCP Server > Edit Config** to edit the active configuration without manually changing JSON. The editor has pages for Server, Security, Permissions, Runtime, and Logging. It covers every runtime setting in the example above; the `version` field and any unknown future fields are preserved when saving.
  179. For security allowlists, enter one Origin or Host per line. The Token field is masked and is required when **Require Bearer token authentication** is enabled. Saving a non-loopback listener without authentication requires confirmation. Restart the MCP HTTP server after saving for server settings to take effect.
  180. ### Remote Access and Security
  181. The server listens on `127.0.0.1` by default. This is intentional: the debugger exposes powerful operations. `security.origin_allowlist` and `security.host_allowlist` validate browser origins and Host headers; they are not passwords or API keys. Use `security.auth_enabled` and `security.auth_token` to enable HTTP Bearer authentication.
  182. #### Local-only (recommended default)
  183. Use `127.0.0.1:3000` and connect from the same Windows host. No firewall rule or port forwarding is required.
  184. #### LAN or VM access
  185. Only do this on a trusted network. Change the bind address and explicitly allow the address used by the client:
  186. ```json
  187. {
  188. "server": { "address": "0.0.0.0", "port": 3000 },
  189. "security": {
  190. "origin_allowlist": ["http://192.168.1.50:3000"],
  191. "host_allowlist": ["192.168.1.20", "debugger.example.test"]
  192. }
  193. }
  194. ```
  195. Use the actual client Origin, server hostname, or server IP. Do not add `*` as an Origin. Open TCP port 3000 only on the required Windows network profile, and configure the VM NAT/bridged adapter or router port forwarding separately. Restart the plugin after changing the file.
  196. Endpoints:
  197. - Streamable HTTP clients: `http://HOST:3000/mcp`
  198. - Legacy HTTP+SSE clients: `http://HOST:3000/sse`
  199. - JSON-RPC compatibility endpoint: `http://HOST:3000/rpc`
  200. - Health check: `GET http://HOST:3000/`
  201. #### Internet access
  202. Do not publish the plugin directly to the Internet. Put it behind a VPN, SSH tunnel, or a reverse proxy that provides TLS, authentication, rate limiting, and IP allowlisting. Keep the plugin bound to `127.0.0.1` when the proxy runs on the same machine. A reverse proxy must preserve the MCP streaming response and forward `Content-Type`, `Accept`, `Mcp-Protocol-Version`, `Mcp-Session-Id`, and `Last-Event-ID` headers.
  203. The plugin supports optional `Authorization: Bearer` validation but does not provide an OAuth authorization server. Never enable memory writes, register writes, or script execution on an unauthenticated public endpoint; these permissions are disabled by default and should remain disabled unless explicitly required.
  204. To enable built-in Bearer authentication, store a high-entropy secret in the plugin configuration and restart the plugin:
  205. ```json
  206. {
  207. "security": {
  208. "auth_enabled": true,
  209. "auth_token": "replace-with-a-long-random-secret"
  210. }
  211. }
  212. ```
  213. All HTTP endpoints except CORS `OPTIONS` preflight then require `Authorization: Bearer <auth_token>`. The server refuses to start if authentication is enabled with an empty token, and logs a security warning when a non-loopback listener starts without authentication. Store the configuration with restrictive filesystem permissions and do not commit the token.
  214. #### Common connection failures
  215. 1. `Connection refused`: verify the plugin server is started, the bind address/port, and VM NAT or firewall rules.
  216. 2. `403` or rejected request: add the exact browser `Origin` to `security.origin_allowlist` and the proxy/client Hostname to `security.host_allowlist`.
  217. 3. MCP initialize succeeds but tools are missing: reconnect after `initialize`; clients discover capabilities from the response.
  218. 4. SSE hangs or returns 404: use `/sse` for legacy SSE clients and `/mcp` for Streamable HTTP clients.
  219. 5. Works through one proxy but not another: check that HTTP/1.1 streaming, long read timeouts, and SSE buffering are enabled.
  220. For a first diagnostic, run `curl http://127.0.0.1:3000/` on the debugger host, then test the same URL through each forwarding layer. Do not include debugger memory or credentials in issue logs.
  221. ### Client Example
  222. Python client example using HTTP:
  223. ```python
  224. import requests
  225. import json
  226. class MCPClient:
  227. def __init__(self, host='127.0.0.1', port=3000):
  228. self.base_url = f"http://{host}:{port}"
  229. self.request_id = 1
  230. def call(self, method, params=None):
  231. request = {
  232. "jsonrpc": "2.0",
  233. "id": self.request_id,
  234. "method": method,
  235. "params": params or {}
  236. }
  237. self.request_id += 1
  238. response = requests.post(
  239. f"{self.base_url}/rpc",
  240. json=request,
  241. headers={"Content-Type": "application/json"}
  242. )
  243. return response.json()
  244. def subscribe_events(self):
  245. """Subscribe to SSE events"""
  246. response = requests.get(
  247. f"{self.base_url}/sse",
  248. stream=True,
  249. headers={"Accept": "text/event-stream"}
  250. )
  251. for line in response.iter_lines():
  252. if line:
  253. yield line.decode('utf-8')
  254. # Usage
  255. client = MCPClient()
  256. print(client.call("initialize"))
  257. print(client.call("tools/list"))
  258. print(client.call("resources/list"))
  259. print(client.call("prompts/list"))
  260. # Subscribe to debug events
  261. for event in client.subscribe_events():
  262. print(f"Event: {event}")
  263. ```
  264. Cursor and other MCP clients usually decide which sections to show from the `initialize` response capabilities. This server advertises `tools`, `resources`, and `prompts`, so after reconnecting you should see all three categories in the client UI.
  265. ### VS Code Integration
  266. Configure in VS Code settings or MCP client config. Recommended (Streamable HTTP, MCP 2025-03-26):
  267. ```json
  268. {
  269. "mcpServers": {
  270. "x64dbg": {
  271. "type": "http",
  272. "url": "http://127.0.0.1:3000/mcp"
  273. }
  274. }
  275. }
  276. ```
  277. Legacy HTTP+SSE clients (use the `/sse` path, not the root):
  278. ```json
  279. {
  280. "mcpServers": {
  281. "x64dbg": {
  282. "type": "sse",
  283. "url": "http://127.0.0.1:3000/sse"
  284. }
  285. }
  286. }
  287. ```
  288. ## Available Methods
  289. ### System Methods
  290. - `system.info` - Get server information
  291. - `system.ping` - Test connection
  292. - `system.methods` - List all available methods
  293. ### Debug Control
  294. - `debug.run` - Continue execution
  295. - `debug.pause` - Pause execution
  296. - `debug.step_into` - Step into instruction
  297. - `debug.step_over` - Step over instruction
  298. - `debug.step_out` - Step out of function
  299. - `debug.get_state` - Get current debug state
  300. - `debug.run_to` - Run to specific address
  301. - `debug.restart` - Restart debugging session
  302. - `debug.stop` - Stop debugging
  303. ### Register Operations
  304. - `register.get` - Read single register
  305. - `register.set` - Write register value
  306. - `register.list` - List all registers
  307. - `register.get_batch` - Read multiple registers
  308. ### Memory Operations
  309. - `memory.read` - Read memory region
  310. - `memory.write` - Write memory region
  311. - `memory.search` - Search memory pattern
  312. - `memory.get_info` - Get memory region info
  313. - `memory.enumerate` - List all memory regions
  314. - `memory.allocate` - Allocate memory
  315. - `memory.free` - Free allocated memory
  316. ### Breakpoint Management
  317. - `breakpoint.set` - Set breakpoint
  318. - `breakpoint.delete` - Remove breakpoint
  319. - `breakpoint.enable` - Enable breakpoint
  320. - `breakpoint.disable` - Disable breakpoint
  321. - `breakpoint.toggle` - Toggle breakpoint state
  322. - `breakpoint.list` - List all breakpoints
  323. - `breakpoint.get` - Get breakpoint details
  324. - `breakpoint.delete_all` - Remove all breakpoints
  325. - `breakpoint.set_condition` - Set breakpoint condition
  326. - `breakpoint.set_log` - Set breakpoint log message
  327. - `breakpoint.reset_hitcount` - Reset breakpoint hit count
  328. ### Disassembly
  329. - `disassembly.at` - Disassemble at address
  330. - `disassembly.range` - Disassemble address range
  331. - `disassembly.function` - Disassemble entire function
  332. ### Symbol Resolution
  333. - `symbol.resolve` - Resolve symbol to address
  334. - `symbol.from_address` - Get symbol from address
  335. - `symbol.search` - Search symbols by pattern
  336. - `symbol.list` - List all symbols
  337. - `symbol.modules` - List loaded modules
  338. - `symbol.set_label` - Set symbol label
  339. - `symbol.set_comment` - Set symbol comment
  340. - `symbol.get_comment` - Get symbol comment
  341. ### Module Operations
  342. - `module.list` - List all loaded modules
  343. - `module.get` - Get module information
  344. - `module.get_main` - Get main module
  345. ### Thread Operations
  346. - `thread.list` - List all threads
  347. - `thread.get_current` - Get current thread
  348. - `thread.get` - Get thread information
  349. - `thread.switch` - Switch to thread
  350. - `thread.suspend` - Suspend thread
  351. - `thread.resume` - Resume thread
  352. - `thread.get_count` - Get thread count
  353. ### Stack Operations
  354. - `stack.get_trace` - Get stack trace
  355. - `stack.read_frame` - Read stack frame
  356. - `stack.get_pointers` - Get stack pointers (RSP/RBP on x64, ESP/EBP on x86)
  357. - `stack.is_on_stack` - Check if address is on stack
  358. For complete method signatures and examples, see the inline documentation in the source code or use the `system.methods` API call.
  359. ## Architecture
  360. The plugin is organized into four layers:
  361. 1. **Communication Layer**: HTTP server with SSE support for real-time events
  362. 2. **Protocol Layer**: JSON-RPC and MCP protocol parsing, validation, dispatching
  363. 3. **Business Layer**: Debugging operations, memory management, symbol resolution
  364. 4. **Plugin Layer**: x64dbg integration, event handling, callback management
  365. ### Key Components
  366. - **MCPHttpServer**: HTTP server with SSE endpoint for event streaming
  367. - **MethodDispatcher**: Routes JSON-RPC calls to appropriate handlers
  368. - **Business Managers**: DebugController, MemoryManager, RegisterManager, etc.
  369. - **Event System**: Real-time debugging event notifications via SSE
  370. ## Security Considerations
  371. - By default, memory and register write operations are **disabled**
  372. - Enable write permissions in `config.json` only if needed
  373. - Server listens on localhost (127.0.0.1) by default
  374. - Single client connection limit prevents resource exhaustion
  375. - All operations require the debugger to be in a paused state
  376. ## Troubleshooting
  377. ### Plugin not loading
  378. - Match the plugin to the debugger: `x64dbg_mcp.dp64` in `x64\plugins\` for x64dbg, or `x32dbg_mcp.dp32` in `x32\plugins\` for x32dbg
  379. - Do not load a `.dp64` plugin in x32dbg or a `.dp32` plugin in x64dbg
  380. - Check the corresponding x64dbg/x32dbg log for error messages
  381. - Verify debugger version compatibility (requires x64dbg/x32dbg build 2023+)
  382. ### Server won't start
  383. - Check if port 3000 is already in use
  384. - Verify config.json is valid JSON
  385. - Check file permissions on the plugin directory
  386. - Review the corresponding x64dbg/x32dbg log file for detailed error messages
  387. ### Connection refused
  388. - Ensure HTTP server is started via plugin menu ("Start MCP HTTP Server")
  389. - Check firewall settings for port 3000
  390. - Verify client is connecting to http://127.0.0.1:3000
  391. - Try accessing http://127.0.0.1:3000 in a web browser to test
  392. ## Contributing
  393. Contributions are welcome! Please:
  394. 1. Fork the repository
  395. 2. Create a feature branch
  396. 3. Make your changes with clear commit messages
  397. 4. Submit a pull request
  398. ## License
  399. This project is licensed under the MIT License - see the LICENSE file for details.
  400. ## Acknowledgments
  401. - [x64dbg](https://x64dbg.com/) - The debugger this plugin extends
  402. - [nlohmann/json](https://github.com/nlohmann/json) - JSON library
  403. - Model Context Protocol specification
  404. ## Contact
  405. - GitHub Issues: For bug reports and feature requests
  406. ---
  407. **Note**: This is experimental software. Use at your own risk. Always test in a safe environment before using with critical applications.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.