{"id":50430522,"url":"https://github.com/memoryforensics1/windbg-mcp","last_synced_at":"2026-05-31T14:01:36.423Z","repository":{"id":358927805,"uuid":"1211948330","full_name":"memoryforensics1/windbg-mcp","owner":"memoryforensics1","description":"C# MCP server for kernel \u0026 user-mode Windows debugging — DbgEng COM, KDNET, Frida, dbgsrv, TTD, and integrated VM control. 29 tools for LLM agents.","archived":false,"fork":false,"pushed_at":"2026-05-19T16:20:21.000Z","size":108,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-19T19:49:30.112Z","etag":null,"topics":["ai-agent","claude","csharp","dbgeng","debugger","dotnet","exploit-development","frida","kernel-debugging","llm","malware-analysis","mcp","model-context-protocol","reverse-engineering","time-travel-debugging","ttd","vmware","vulnerability-research","windbg","windows"],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/memoryforensics1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-15T23:08:07.000Z","updated_at":"2026-05-19T16:56:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/memoryforensics1/windbg-mcp","commit_stats":null,"previous_names":["memoryforensics1/windbg-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/memoryforensics1/windbg-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/memoryforensics1%2Fwindbg-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/memoryforensics1%2Fwindbg-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/memoryforensics1%2Fwindbg-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/memoryforensics1%2Fwindbg-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/memoryforensics1","download_url":"https://codeload.github.com/memoryforensics1/windbg-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/memoryforensics1%2Fwindbg-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33733754,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","claude","csharp","dbgeng","debugger","dotnet","exploit-development","frida","kernel-debugging","llm","malware-analysis","mcp","model-context-protocol","reverse-engineering","time-travel-debugging","ttd","vmware","vulnerability-research","windbg","windows"],"created_at":"2026-05-31T14:01:35.544Z","updated_at":"2026-05-31T14:01:36.417Z","avatar_url":"https://github.com/memoryforensics1.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WinDbg MCP Server\n\nA [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that gives AI agents complete control over a Windows VM for kernel debugging, reverse engineering, malware analysis, and vulnerability research.\n\nBuilt in C# (.NET 8), it wraps the Windows Debugger Engine (DbgEng COM), VMware Workstation, Frida, and dbgsrv into **29 MCP tools** that any MCP-compatible LLM client can call.\n\n![Architecture](https://img.shields.io/badge/.NET_8-512BD4?logo=dotnet\u0026logoColor=white)\n![Platform](https://img.shields.io/badge/Windows-0078D6?logo=windows\u0026logoColor=white)\n![VMware](https://img.shields.io/badge/VMware_Workstation-607078?logo=vmware\u0026logoColor=white)\n![License](https://img.shields.io/badge/license-MIT-green)\n\n## Why this project?\n\nOther WinDbg MCP servers exist — most are Python wrappers that launch `cdb.exe` or `windbg.exe` as a subprocess and drive it over stdin/stdout. That's easy to prototype but fragile in practice: the child debugger crashes, hangs on modal dialogs, deadlocks its own pipes, or dies mid-session and takes the agent's context with it.\n\nThis project takes a different approach:\n\n- **Direct DbgEng COM** — calls the Windows Debugger Engine natively through its COM interface. No subprocess to babysit, no stdout parsing, no hung pipes. Commands execute inside the server process on a dedicated MTA COM thread with an event pump — so the debugger can't drag the whole MCP server down with it.\n- **Kernel debugging is the primary use case, not an afterthought** — full KDNET integration: attach to a running kernel, set breakpoints, step, run any WinDbg command while the target is halted, wait for events with hard timeouts, detect BSODs, and pass first-chance exceptions through so Windows keeps running normally. Execution-control commands (`g`/`t`/`p`) are blocked in `kd_execute` so the LLM can't accidentally run away from a breakpoint — it has to use the explicit `kd_continue`/`kd_step` tools, which always return.\n- **User-mode is covered too** — Frida (with eternalized hooks for persistent instrumentation across sessions), dbgsrv for noninvasive process inspection with full WinDbg command access, and TTD (Time Travel Debugging) — all behind the same server.\n- **VM lifecycle is integrated with the debug session** — snapshot restore cleanly tears down KD/Frida/dbgsrv before reverting the VM; guest commands, file transfer, and process control are all gated on VM power state so the agent never trips on \"wrong state\" errors. `vm_set_target` lets a running server switch to a different VM at runtime.\n- **Designed for LLM agents** — every tool has a hard timeout (nothing blocks forever), every error message explicitly tells the LLM what to do next, and `get_system_state` gives the model a single \"where am I?\" snapshot on demand. A `StateCoordinator` validates preconditions before every call so the agent gets useful feedback instead of silent failures.\n\n## What Can It Do?\n\nAn LLM connected to this server can autonomously:\n\n- **Control a VM** — start, stop, pause, resume, snapshot, restore, screenshot\n- **Kernel debug** — connect via KDNET, set breakpoints, step, execute any WinDbg command, wait for events\n- **Run commands in the guest** — execute programs, transfer files, list/kill processes\n- **User-mode debug** — attach Frida to hook functions, inspect processes via dbgsrv, record TTD traces\n\nAll without the LLM ever needing direct access to WinDbg, a terminal, or the VM itself.\n\n## Quick Start\n\n### Prerequisites\n\n| Requirement | Purpose |\n|---|---|\n| [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) | Build \u0026 run the server |\n| [VMware Workstation Pro](https://www.vmware.com/products/workstation-pro.html) | VM management (vmrun) |\n| Windows Guest VM | Target for debugging |\n| KDNET enabled in guest | Kernel debugging (see [Setup](#vm-setup)) |\n| [frida-tools](https://frida.re/) *(optional)* | User-mode instrumentation |\n| [WinDbg Preview](https://aka.ms/windbg) *(optional)* | Provides dbgsrv.exe for remote user-mode debugging |\n\n### 1. Clone \u0026 Build\n\n```bash\ngit clone https://github.com/memoryforensics1/windbg-mcp.git\ncd windbg-mcp\ndotnet build src/WinDbgMCP.Server/WinDbgMCP.Server.csproj\n```\n\n### 2. Configure *(optional)*\n\n\u003cdetails\u003e\n\u003csummary\u003eEverything in \u003ccode\u003eappsettings.json\u003c/code\u003e is just a default — the LLM can change VM target, credentials, KDNET key, and more at runtime via \u003ccode\u003evm_set_target\u003c/code\u003e. Expand only if you want to set a starting config.\u003c/summary\u003e\n\nCopy `src/WinDbgMCP.Server/appsettings.example.json` to `appsettings.json` and edit:\n\n```json\n{\n  \"Vm\": {\n    \"VmxPath\": \"C:\\\\path\\\\to\\\\your\\\\vm.vmx\",\n    \"VmrunPath\": \"C:\\\\Program Files (x86)\\\\VMware\\\\VMware Workstation\\\\vmrun.exe\",\n    \"VmPassword\": \"\",\n    \"GuestUsername\": \"YourUser\",\n    \"GuestPassword\": \"YourPass\"\n  },\n  \"KernelDebug\": {\n    \"Transport\": \"kdnet\",\n    \"Kdnet\": {\n      \"Port\": 50000,\n      \"Key\": \"your.kdnet.key.here\"\n    },\n    \"SymbolPath\": \"srv*C:\\\\Symbols*https://msdl.microsoft.com/download/symbols\"\n  },\n  \"Guest\": {\n    \"FridaPort\": 27042,\n    \"DbgsrvPort\": 5064\n  }\n}\n```\n\n\u003c/details\u003e\n\n### 3. Add to Your MCP Client\n\n**Claude Code** (`.mcp.json` in project root):\n```json\n{\n  \"mcpServers\": {\n    \"windbg-mcp\": {\n      \"command\": \"dotnet\",\n      \"args\": [\"run\", \"--project\", \"C:\\\\path\\\\to\\\\windbg-mcp\\\\src\\\\WinDbgMCP.Server\\\\WinDbgMCP.Server.csproj\"]\n    }\n  }\n}\n```\n\n**Claude Desktop** (`claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"windbg-mcp\": {\n      \"command\": \"C:\\\\Program Files\\\\dotnet\\\\dotnet.exe\",\n      \"args\": [\"run\", \"--project\", \"C:\\\\path\\\\to\\\\windbg-mcp\\\\src\\\\WinDbgMCP.Server\\\\WinDbgMCP.Server.csproj\"]\n    }\n  }\n}\n```\n\n### 4. Run\n\nThe server starts automatically when your MCP client connects. It communicates over stdio.\n\n```bash\n# Or run standalone for testing\ndotnet run --project src/WinDbgMCP.Server/WinDbgMCP.Server.csproj\n```\n\n## Tool Catalog (29 tools)\n\n### Meta\n| Tool | Description |\n|---|---|\n| `get_system_state` | Full state overview — VM power, KD, guest ops, UMD. Always allowed. |\n\n### VM Tools (8)\n| Tool | Description |\n|---|---|\n| `vm_start` | Power on the VM |\n| `vm_stop` | Shut down (graceful or hard) |\n| `vm_pause` | Freeze entire VM |\n| `vm_resume` | Unpause a paused VM |\n| `vm_snapshot_restore` | Restore a named snapshot (debug sessions are cleanly torn down and can reconnect after) |\n| `vm_snapshot_list` | List available snapshots |\n| `vm_screenshot` | Capture VM display as PNG |\n| `vm_set_target` | Switch the active VM target at runtime (VMX path + credentials) |\n\n### Kernel Debug Tools (7)\n| Tool | Description |\n|---|---|\n| `kd_connect` | Attach to kernel via KDNET. Target breaks on connect. |\n| `kd_disconnect` | Detach from kernel. Resumes target so VM keeps running. |\n| `kd_break` | Halt running target (Ctrl+Break) |\n| `kd_continue` | Resume target execution |\n| `kd_step` | Step one instruction (into or over) |\n| `kd_execute` | Run any WinDbg command (`k`, `r`, `lm`, `!process 0 0`, `!analyze -v`, etc.) |\n| `kd_wait_for_event` | Wait for breakpoint/exception with timeout. Always returns. |\n\n### Guest Tools (5)\n| Tool | Description |\n|---|---|\n| `guest_run_command` | Execute command in guest OS, capture stdout/stderr |\n| `guest_transfer_to_vm` | Copy file from host to guest |\n| `guest_transfer_from_vm` | Copy file from guest to host |\n| `guest_list_processes` | List running processes with PIDs |\n| `guest_kill_process` | Kill a process by PID |\n\n### User-Mode Debug Tools (8)\n| Tool | Description |\n|---|---|\n| `umd_frida_attach` | Attach Frida to a guest process |\n| `umd_frida` | Inject JS, eval expressions, list processes, detach |\n| `umd_frida_skill` | Frida best practices and API reference for LLMs |\n| `umd_dbgsrv_connect` | Connect to remote dbgsrv in guest |\n| `umd_dbgsrv_execute` | Attach to PID, run WinDbg commands, detach |\n| `umd_dbgsrv_skill` | dbgsrv best practices and WinDbg command reference for LLMs |\n| `umd_ttd` | Time Travel Debugging — record, stop, retrieve, list traces |\n| `umd_ttd_query` | Query TTD traces *(not yet implemented)* |\n\n## Example Workflows\n\n### Inspect a Running Kernel\n\n```\nget_system_state\nkd_connect\nkd_execute(\"lm\")                    # list loaded modules\nkd_execute(\"!process 0 0\")          # list all processes\nkd_execute(\"vertarget\")             # target version info\nkd_disconnect\n```\n\n### Set Breakpoint and Catch It\n\n```\nkd_connect\nkd_execute(\"bp nt!NtCreateFile\")    # set breakpoint\nkd_continue                          # let target run\nkd_wait_for_event(30)               # wait up to 30s for hit\nkd_execute(\"k\")                     # show call stack\nkd_execute(\"r\")                     # show registers\nkd_disconnect\n```\n\n### Deploy and Debug a Driver\n\n```\nguest_transfer_to_vm(\"MyDriver.sys\", \"C:\\\\Windows\\\\System32\\\\drivers\\\\MyDriver.sys\")\nguest_run_command(\"sc create MyDrv type= kernel binPath= C:\\\\Windows\\\\System32\\\\drivers\\\\MyDriver.sys\")\nguest_run_command(\"sc start MyDrv\")\nkd_connect\nkd_execute(\"lm m MyDrv\")            # verify driver loaded\nkd_execute(\"bp MyDrv!DriverEntry\")\nkd_disconnect\n```\n\n### Hook a Function with Frida\n\n```\numd_frida_skill                      # read best practices first\numd_frida_attach(processName=\"target.exe\")\numd_frida(action=\"eval\", code=\"Process.enumerateModules().map(m=\u003em.name)\")\numd_frida(action=\"inject\", code=\"\"\"\n  Interceptor.attach(Module.getExportByName('kernel32.dll','CreateFileW'), {\n    onEnter(args) { console.log('CreateFileW: ' + args[0].readUtf16String()); }\n  });\n  console.log('Hook installed');\n\"\"\", timeoutSeconds=10)\numd_frida(action=\"detach\")\n```\n\n### Inspect a Process with dbgsrv\n\n```\numd_dbgsrv_skill                     # read best practices first\nguest_run_command(\"start /b C:\\\\Tools\\\\DbgSrv\\\\dbgsrv.exe -t tcp:port=5064\")\numd_dbgsrv_connect(vmIpAddress=\"192.168.x.x\")\numd_dbgsrv_execute(action=\"attach\", argument=\"\u003cPID\u003e\")\numd_dbgsrv_execute(action=\"command\", argument=\"lm\")\numd_dbgsrv_execute(action=\"command\", argument=\"!peb\")\numd_dbgsrv_execute(action=\"command\", argument=\"~*k\")\numd_dbgsrv_execute(action=\"detach\")\numd_dbgsrv_execute(action=\"disconnect\")\n```\n\n### Crash Analysis\n\n```\nkd_connect                           # connect after BSOD\nkd_execute(\"!analyze -v\")           # automated crash analysis\nkd_execute(\"k\")                     # faulting stack\nkd_execute(\"r\")                     # registers at crash\nkd_execute(\".trap\")                 # switch to trap frame\nkd_disconnect\n```\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                      MCP Client (LLM)                       │\n│                  Claude Code / Claude Desktop                │\n└──────────────────────────┬──────────────────────────────────┘\n                           │ stdio (JSON-RPC)\n┌──────────────────────────▼──────────────────────────────────┐\n│                    WinDbgMCP.Server                          │\n│                                                              │\n│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │\n│  │  VM Tools    │  │  KD Tools    │  │  Guest Tools     │  │\n│  │  (vmrun)     │  │  (DbgEng)    │  │  (vmrun guest)   │  │\n│  └──────┬───────┘  └──────┬───────┘  └──────┬───────────┘  │\n│         │                 │                  │               │\n│  ┌──────▼───────┐  ┌──────▼───────┐  ┌──────▼───────────┐  │\n│  │ VmwareManager│  │ DbgEngManager│  │ GuestExecManager │  │\n│  └──────────────┘  └──────┬───────┘  └──────────────────┘  │\n│                           │                                  │\n│  ┌────────────────────────▼─────────────────────────────┐   │\n│  │              StateCoordinator                         │   │\n│  │   (precondition gate — validates every tool call)     │   │\n│  └───────────────────────────────────────────────────────┘   │\n│                                                              │\n│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │\n│  │ UMD: Frida   │  │ UMD: dbgsrv  │  │ UMD: TTD         │  │\n│  │ (frida CLI)  │  │ (DbgEng COM) │  │ (TTD.exe)        │  │\n│  └──────────────┘  └──────────────┘  └──────────────────┘  │\n└──────────────────────────────────────────────────────────────┘\n         │                    │                    │\n         ▼                    ▼                    ▼\n┌─────────────────────────────────────────────────────────────┐\n│                   Windows Guest VM                           │\n│              (VMware Workstation Pro)                         │\n│                                                              │\n│  KDNET (:50000)  │  frida-server (:27042)  │  dbgsrv (:5064)│\n└─────────────────────────────────────────────────────────────┘\n```\n\n### Key Design Principles\n\n1. **Every tool validates preconditions** — `StateCoordinator` checks VM power, KD state, guest ops availability before any operation executes\n2. **Every operation has a timeout** — no blocking calls, ever. The LLM never hangs.\n3. **Error messages are prompts** — every error tells the LLM exactly what to do next\n4. **Execution-control commands are blocked** — `g`, `t`, `p` are blocked in `kd_execute`; use `kd_continue`/`kd_step` instead\n5. **DbgEng COM thread affinity** — all COM calls marshaled to a dedicated MTA thread with an event pump\n6. **BSOD detection** — bugchecks are detected and handled differently from normal breakpoints\n7. **Snapshot restore resets everything** — KD, Frida, dbgsrv sessions are all cleaned up\n\n## VM Setup\n\n### Enable KDNET (Kernel Debugging)\n\nIn the guest VM (elevated cmd):\n\n```cmd\nbcdedit /debug on\nbcdedit /dbgsettings net hostip:\u003cHOST_IP\u003e port:50000 key:\u003cYOUR_KEY\u003e\nshutdown /r /t 0\n```\n\nGenerate a key with `kdnet.exe` from the Windows SDK, or use any dotted-quad format key.\n\n### Install Frida Server (Optional)\n\nOn the **host**:\n```bash\npip install frida-tools\n```\n\nDownload `frida-server-\u003cversion\u003e-windows-x86_64.exe` from [Frida releases](https://github.com/frida/frida/releases), deploy to guest as `C:\\Tools\\frida-server.exe`, and run:\n```cmd\nfrida-server.exe -l 0.0.0.0:27042\n```\n\n### Install dbgsrv (Optional)\n\nCopy `dbgsrv.exe`, `dbgeng.dll`, and `dbghelp.dll` from WinDbg Preview (or Windows SDK) to the guest, then run:\n```cmd\ndbgsrv.exe -t tcp:port=5064\n```\n\n### Firewall\n\nThe host firewall must allow:\n- UDP port 50000 inbound (KDNET)\n- TCP port 27042 outbound (Frida)\n- TCP port 5064 outbound (dbgsrv)\n\n## Project Structure\n\n```\nsrc/WinDbgMCP.Server/\n├── Program.cs                    # Entry point, MCP server setup, DI\n├── appsettings.json              # Configuration (VM creds, KDNET, timeouts)\n├── Configuration/\n│   └── ServerConfig.cs           # Typed configuration model\n├── State/\n│   ├── SystemState.cs            # State model + enums\n│   ├── StateCoordinator.cs       # Precondition gate (heart of system)\n│   ├── ErrorMessages.cs          # LLM-friendly error catalog\n│   └── ToolResult.cs             # Result type\n├── Vmware/\n│   └── VmwareManager.cs          # vmrun wrapper\n├── KernelDebug/\n│   ├── DbgEngThread.cs           # Dedicated MTA thread for COM\n│   ├── DbgEngManager.cs          # Kernel debug session manager\n│   ├── DebugEventCallbacks.cs    # Breakpoint/exception/module events\n│   ├── OutputCapture.cs          # Command output capture\n│   └── Interop/                  # P/Invoke, constants\n├── Guest/\n│   └── GuestExecManager.cs       # Guest command execution + file transfer\n├── UserModeDebug/\n│   ├── FridaManager.cs           # Frida CLI wrapper\n│   ├── DbgsrvManager.cs          # Remote user-mode debugging via dbgsrv\n│   └── TtdManager.cs             # Time Travel Debugging\n└── Tools/\n    ├── VmTools.cs                # vm_* tools\n    ├── KernelDebugTools.cs       # kd_* tools\n    ├── GuestTools.cs             # guest_* tools\n    ├── UserModeDebugTools.cs     # umd_* tools\n    └── MetaTools.cs              # get_system_state\n\nsrc/WinDbgMCP.Tests/              # Unit tests (126 tests)\n```\n\n## Running Tests\n\n```bash\ndotnet test src/WinDbgMCP.Tests/WinDbgMCP.Tests.csproj\n```\n\n## Tech Stack\n\n| Component | Technology |\n|---|---|\n| Runtime | .NET 8 (C#) |\n| MCP SDK | [ModelContextProtocol](https://github.com/modelcontextprotocol/csharp-sdk) 0.1.0-preview.12 |\n| DbgEng | Native COM interop (`dbgeng.dll`) |\n| VM Control | VMware vmrun CLI |\n| User-Mode Hooking | Frida (frida-tools Python CLI) |\n| Remote Debugging | dbgsrv.exe (WinDbg component) |\n| TTD | TTD.exe (Time Travel Debugging) |\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmemoryforensics1%2Fwindbg-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmemoryforensics1%2Fwindbg-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmemoryforensics1%2Fwindbg-mcp/lists"}