README.md
Direct kernel debugger MCP server for Windows security research.
Aragorn
Direct kernel debugger MCP server for Windows security research. Connects to Windows VM kernels via kdnet and exposes 63 tools over the Model Context Protocol.
This process is the debugger. It spawns kd.exe as a subprocess for kdnet transport, then connects via DebugConnect() for full DbgEng COM access. No WinDbg GUI required.
MCP Client ──stdio/http──► Aragorn ──DebugConnect(TCP)──► kd.exe ──kdnet──► VM kernel
Quick Start
# 1. Install dependencies
pip install -r requirements.txt
# 2. Copy DbgEng DLLs from WinDbg Preview into dbgeng_bin/
# (dbgeng.dll, dbghelp.dll, dbgmodel.dll, dbgcore.dll, symsrv.dll, srcsrv.dll)
# 3. Configure
cp .env.example .env
# Edit .env: set KD_CONNECTION, KD_EXE_PATH, etc.
# 4. Run (stdio mode — for MCP clients like Claude Code)
python server.py
# Or HTTP mode (for remote/shared access)
python server.py --http
.mcp.json integration
{
"aragorn": {
"type": "stdio",
"command": "python",
"args": ["path/to/Aragorn/server.py"]
}
}
Configuration
All settings are via environment variables (or .env file):
| Variable | Default | Description |
|---|---|---|
KD_CONNECTION |
net:port=55555,key=...,target=... |
kdnet connection string |
KD_EXE_PATH |
WinDbg Preview's kd.exe | Path to kd.exe |
KD_SERVER_PORT |
14500 |
Local TCP port for kd.exe debug server |
DBGENG_PATH |
./dbgeng_bin/dbgeng.dll |
Path to DbgEng DLL |
SYMBOL_PATH |
Microsoft symbol server | Symbol search path |
ARAGORN_HOST |
127.0.0.1 |
HTTP mode bind address |
ARAGORN_PORT |
14401 |
HTTP mode port |
VM_AGENT_URL |
http://YOUR_VM_IP:8080 |
VM agent URL (for workflow tools) |
VM_AGENT_API_KEY |
(empty) | VM agent API key |
DbgEng Binaries
The dbgeng_bin/ directory is gitignored. Copy these DLLs from your WinDbg Preview installation:
C:\Program Files\WindowsApps\Microsoft.WinDbg_*\amd64\
├── dbgeng.dll
├── dbghelp.dll
├── dbgmodel.dll
├── dbgcore.dll
├── symsrv.dll
└── srcsrv.dll
VM Agent
The vm_agent/ directory contains a lightweight Flask server that runs inside the target VM. It exposes process execution, file I/O, and driver service management over HTTP. Aragorn's workflow tools (breakpoint_and_run, vm_exec, etc.) use it to coordinate kernel debugging with VM-side actions.
# On the VM:
cd vm_agent
pip install -r requirements.txt
cp .env.example .env
# Edit .env: set VM_AGENT_API_KEY
python server.py
The VM agent is optional — all pure debugger tools work without it. You only need it for the coordinated workflow tools.
Tools
Session & Connection (9)
| Tool | Description |
|---|---|
connect |
Connect to kernel debugger via kd.exe |
disconnect |
Cleanly disconnect |
status |
Get connection state and config |
target_info |
Get debug target info (class, processors, page size) |
ensure_ready |
Break in, verify context, reload symbols (retries 5x) |
health_check |
Lightweight probe without breaking into target |
reconnect_debugger |
Force full reconnect |
test_kd_connection |
Diagnostic kd.exe connection test |
get_debugger_state |
Full tracked state for cross-agent coordination |
Multi-Session (6)
| Tool | Description |
|---|---|
session_create |
Create isolated debugger session for a VM |
session_connect |
Connect a session's debugger |
session_disconnect |
Disconnect without destroying |
session_destroy |
Destroy and clean up a session |
session_list |
List all sessions with status |
session_set_active |
Set active session for tool routing |
Command Execution (3)
| Tool | Description |
|---|---|
execute |
Execute raw debugger command (e.g., lm, !process 0 0) |
execute_batch |
Execute multiple commands sequentially |
evaluate |
Evaluate expression, return numeric value |
Memory (7)
| Tool | Description |
|---|---|
read_memory |
Read virtual memory (hex/qwords/dwords/ascii) |
write_memory |
Write bytes to virtual memory |
search_memory |
Search for byte pattern |
read_physical |
Read physical memory |
write_physical |
Write to physical memory |
virtual_to_physical |
Translate virtual to physical address |
read_msr |
Read Model-Specific Register |
Registers (2)
| Tool | Description |
|---|---|
read_registers |
Read all general-purpose registers |
write_register |
Write a register value |
Stack (1)
| Tool | Description |
|---|---|
get_stack |
Get structured stack trace with symbols |
Breakpoints (4)
| Tool | Description |
|---|---|
set_breakpoint |
Set code or data/hardware breakpoint |
remove_breakpoint |
Remove breakpoint by ID |
list_breakpoints |
List all breakpoints with status |
set_exception_filter |
Configure exception handling (break/ignore/output) |
Execution Control (4)
| Tool | Description |
|---|---|
| `con |
Tools (9)
connectConnect to kernel debugger via kd.exedisconnectCleanly disconnectstatusGet connection state and configtarget_infoGet debug target info (class, processors, page size)executeExecute raw debugger command (e.g., lm, !process 0 0)read_memoryRead virtual memory (hex/qwords/dwords/ascii)write_memoryWrite bytes to virtual memoryset_breakpointSet code or data/hardware breakpointget_stackGet structured stack trace with symbolsEnvironment Variables
KD_CONNECTIONkdnet connection stringKD_EXE_PATHPath to kd.exeDBGENG_PATHPath to DbgEng DLLSYMBOL_PATHSymbol search pathVM_AGENT_URLVM agent URL for workflow toolsConfiguration
claude_desktop_config.json
{"aragorn": {"type": "stdio", "command": "python", "args": ["path/to/Aragorn/server.py"]}}Try it
→Connect to the target VM kernel and provide the current target information.
→Execute the debugger command '!process 0 0' to list all running processes.
→Read the memory at the current instruction pointer address.
→Set a hardware breakpoint on the specified memory address.
→Get the current stack trace for the active thread.