Skip to content

Commit d5a352a

Browse files
dariushouledariushoule
committed
Add an official MCP server
1 parent 30c64d1 commit d5a352a

File tree

11 files changed

+2699
-120
lines changed

11 files changed

+2699
-120
lines changed

‎.claude/settings.local.json‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"Bash(dir:*)",
5+
"Bash(find:*)",
6+
"Bash(pip install:*)",
7+
"Bash(python -m pytest:*)",
8+
"mcp__x64dbg__get_all_registers",
9+
"mcp__x64dbg__step_into",
10+
"mcp__x64dbg__get_register",
11+
"mcp__x64dbg__disassemble",
12+
"mcp__x64dbg__start_session",
13+
"mcp__x64dbg__get_debugger_status",
14+
"mcp__x64dbg__get_symbol",
15+
"mcp__x64dbg__read_memory"
16+
]
17+
},
18+
"enableAllProjectMcpServers": true,
19+
"enabledMcpjsonServers": [
20+
"x64dbg"
21+
]
22+
}

‎.mcp.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"mcpServers": {
3+
"x64dbg": {
4+
"command": "poetry",
5+
"args": ["run", "x64dbg-automate-mcp"],
6+
"cwd": "."
7+
}
8+
}
9+
}

‎CLAUDE.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# CLAUDE.md
2+
3+
## Project
4+
Python client library for x64dbg Automate — RPC-based automation of x64dbg debugger via ZMQ/msgpack.
5+
6+
## Commands
7+
```powershell
8+
poetry install # install deps
9+
python -m pytest # run tests (requires running x64dbg with plugin)
10+
python -m mkdocs serve # docs dev server
11+
```
12+
13+
## Test env vars
14+
- `TEST_BITNESS` — 32 or 64 (default: 64)
15+
- `X64DBG_PATH` — path to x64dbg executable
16+
17+
## Architecture
18+
Mixin chain: `XAutoClientBase` → `XAutoCommandsMixin` (low-level RPC) → `XAutoHighLevelCommandAbstractionMixin` (convenience methods) → `X64DbgClient` (also mixes in `DebugEventQueueMixin`).
19+
20+
ZMQ REQ/REP for sync commands, PUB/SUB for async events. Msgpack serialization. Thread-safe via `_req_lock`.
21+
22+
## Conventions
23+
- Type hints everywhere, modern union syntax (`X | None` not `Optional[X]`)
24+
- Pydantic models for data structures (`models.py`)
25+
- Google-style docstrings (Args/Returns/Raises)
26+
- snake_case functions, PascalCase classes, UPPER_CASE constants
27+
- Private methods prefixed with `_`
28+
- Enums use `StrEnum`/`IntEnum`
29+
- No unnecessary abstractions — keep it direct

‎docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ The heart of the project is the native plugin that externalizes the bridge and s
1515
- **Maintained/Modern Plugin and Client**: Automate aims to target both the latest x64dbg and Python versions.
1616
- **Clear Documentation**: The features of Automate are easy to understand and well documented.
1717
- **Extensible**: Build on top of Automate to extend its capabilities even further.
18+
- **Agent Friendly**: Supports the MCP protocol for agentic access.
1819

1920
## Getting Started
2021

‎docs/installation.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,12 @@ Extract the entire contents of the archive's `Release` directory into your debug
2323
pip install x64dbg_automate --upgrade
2424
```
2525

26+
To also install the MCP server for use with Claude Code or other MCP-compatible clients:
27+
28+
```sh
29+
pip install x64dbg_automate[mcp] --upgrade
30+
```
31+
2632
🔔 Important: The Microsoft Store builds of Python are restricted such that the client library may not function well. Use them at your own risk.
2733

2834

‎docs/mcp-server.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# MCP Server
2+
3+
### What is the MCP Server?
4+
5+
The x64dbg Automate MCP server exposes the debugger's capabilities as [Model Context Protocol](https://modelcontextprotocol.io/) tools. This allows LLM clients like Claude Code to directly control x64dbg for reverse engineering, malware analysis, and debugging tasks.
6+
7+
The MCP server wraps the same Python API documented in the Client Reference sections, so all the same functionality is available.
8+
9+
### Installation
10+
11+
Install the client library with the `mcp` extra:
12+
13+
```sh
14+
pip install x64dbg_automate[mcp] --upgrade
15+
```
16+
17+
### Claude Code Configuration
18+
19+
Add the following to your Claude Code MCP settings. You can do this via the CLI:
20+
21+
```sh
22+
claude mcp add x64dbg -- x64dbg-automate-mcp
23+
```
24+
25+
Or manually create/edit `.mcp.json` in your project root:
26+
27+
```json
28+
{
29+
"mcpServers": {
30+
"x64dbg": {
31+
"command": "x64dbg-automate-mcp"
32+
}
33+
}
34+
}
35+
```
36+
37+
Restart Claude Code after adding the configuration. You will be prompted to approve the MCP server on first use.
38+
39+
### Available Tools
40+
41+
The MCP server provides ~40 tools organized into the following groups:
42+
43+
| Group | Tools | Description |
44+
|-------|-------|-------------|
45+
| Session | `list_sessions`, `start_session`, `connect_to_session`, `disconnect`, `terminate_session` | Manage debugger instances |
46+
| Debug Control | `go`, `pause`, `step_into`, `step_over`, `skip_instruction`, `run_to_return`, `get_debugger_status` | Control execution |
47+
| Memory | `read_memory`, `write_memory`, `allocate_memory`, `free_memory`, `get_memory_map` | Read/write debuggee memory |
48+
| Registers | `get_register`, `set_register`, `get_all_registers` | Register access |
49+
| Expressions | `eval_expression`, `execute_command` | x64dbg expression evaluator and raw commands |
50+
| Breakpoints | `set_breakpoint`, `clear_breakpoint`, `toggle_breakpoint`, `list_breakpoints` | Software, hardware, and memory breakpoints |
51+
| Assembly | `disassemble`, `assemble` | Disassemble and assemble instructions |
52+
| Annotations | `set_label`, `get_label`, `set_comment`, `get_comment`, `get_symbol` | Labels, comments, and symbol lookup |
53+
| Threads | `create_thread`, `terminate_thread`, `pause_resume_thread`, `switch_thread` | Thread management |
54+
| Events | `get_latest_event`, `wait_for_event` | Debug event queue |
55+
| Settings | `get_setting`, `set_setting` | x64dbg configuration |
56+
| GUI | `log_message`, `refresh_gui` | Debugger UI interaction |
57+
58+
### Walkthrough: Debugging with Claude
59+
60+
This walkthrough demonstrates a typical analysis session using the MCP server from Claude Code. The x64dbg plugin must be installed and the MCP server configured as described above.
61+
62+
**Step 1: Start a session**
63+
64+
Ask Claude to start a debug session:
65+
66+
```
67+
Launch x64dbg from C:\x64dbg\release and debug C:\targets\to_analyze.exe
68+
```
69+
70+
Claude will call `start_session` with your x64dbg path and target executable.
71+
72+
**Step 2: Explore the target**
73+
74+
Ask Claude to look around:
75+
76+
```
77+
Disassemble the first 20 instructions at the entry point
78+
```
79+
80+
Claude will call `disassemble` with `RIP` as the address (resolved via x64dbg's expression evaluator), giving you annotated disassembly output.
81+
82+
```
83+
Show me the memory map and read 256 bytes at RSP
84+
```
85+
86+
Claude will call `get_memory_map` and `read_memory`, returning a hex dump with ASCII sidebar.
87+
88+
**Step 3: Set breakpoints and run**
89+
90+
```
91+
Set a breakpoint on MessageBoxA and resume execution
92+
```
93+
94+
Claude will call `set_breakpoint` with the symbol name and then `go` to resume.
95+
96+
**Step 4: Inspect state at a breakpoint**
97+
98+
```
99+
Show me all registers and disassemble 10 instructions at the current position
100+
```
101+
102+
Claude will call `get_all_registers` and `disassemble` with `RIP`, giving you a full picture of the current state.
103+
104+
**Step 5: Modify and continue**
105+
106+
```
107+
Write 0x90 0x90 (NOPs) at 0x401032 and step over 5 instructions
108+
```
109+
110+
Claude will call `write_memory` to patch the bytes and `step_over` to advance.
111+
112+
**Step 6: Clean up**
113+
114+
```
115+
Disconnect from the debugger
116+
```
117+
118+
Claude will call `disconnect`, leaving x64dbg running for manual inspection, or `terminate_session` to close it entirely.
119+
120+
### Tips
121+
122+
- **Let Claude drive**: Describe your analysis goal in plain language. Claude can chain multiple tools together to investigate, set breakpoints, read memory, and modify state.
123+
- **Expressions work everywhere**: Any tool that takes an address also accepts registers, symbols, and arithmetic expressions — just like the x64dbg command bar.
124+
- **Memory reads are capped**: `read_memory` is limited to 4096 bytes per call and `disassemble` to 100 instructions. Ask for multiple reads if you need more.
125+
- **Events for synchronization**: Use `wait_for_event` to wait for breakpoints, DLL loads, or other debug events before inspecting state.
126+
- **Raw commands**: If a feature isn't exposed as a dedicated tool, `execute_command` passes any command directly to x64dbg's command interpreter. See the [x64dbg command reference](https://help.x64dbg.com/en/latest/commands/).

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ nav:
55
- "Home": index.md
66
- "Installation": installation.md
77
- "Quickstart": quickstart.md
8+
- "MCP Server": mcp-server.md
89
- "Client Reference":
910
- "Session Control": api/session-control.md
1011
- "Debug Control": api/debug-control.md

0 commit comments

Comments
 (0)