What is Windbg Ext Mcp

WinDbg-ext-MCP is a tool that bridges your favorite LLM client (like Cursor, Claude, or VS Code) with WinDbg, enabling real-time, AI-assisted kernel debugging through natural language prompts.

Use cases

Use cases include debugging Windows kernel issues, automating debugging tasks with AI assistance, and enhancing the debugging process through natural language interactions.

How to use

To use WinDbg-ext-MCP, connect your LLM client to the Python MCP server, which communicates with WinDbg. When a breakpoint is hit during a debugging session, you can write prompts in your LLM client to receive context-aware analysis and insights.

Key features

Key features include session management, command execution optimization, LLM automation for AI-driven debugging, process and thread analysis, and real-time kernel information retrieval.

Where to use

WinDbg-ext-MCP is primarily used in network-based kernel debugging scenarios, particularly with Windows virtual machines.

WinDbg-ext-MCP

Vibe debugging your Windows kernel!

WinDbg-ext-MCP connects your LLM client (like Cursor, Claude, or VS Code) with WinDbg, enabling AI kernel debugging through natural language prompts. Designed for network-based kernel debugging scenarios with Windows VMs.

🎯 Overview

This project enables you to debug Windows kernels using WinDbg while leveraging the power of LLMs (like Claude, GPT, etc.) through natural language interactions. When you hit a breakpoint in WinDbg while debugging a Windows VM over the network, you can write prompts in Cursor (or any MCP-compatible client) to get detailed kernel information and analysis.

🏗️ Architecture

The project uses a hybrid architecture optimized for network kernel debugging:

┌─────────────┐    stdio     ┌──────────────────┐    named pipe   ┌─────────────┐    network    ┌─────────────┐
│   Cursor    │◄────────────►│  Python MCP      │◄───────────────►│   WinDbg    │◄─────────────►│ Target VM   │
│   (Client)  │              │    Server        │                 │ Extension   │               │  (Kernel)   │
└─────────────┘              └──────────────────┘                 └─────────────┘               └─────────────┘

Components

1. MCP Client (Cursor/IDE): Natural language interface
2. Python MCP Server (mcp_server/): Core logic, optimization, and tool orchestration
3. WinDbg Extension (extension/): C++ DLL for WinDbg integration
4. WinDbg: Debugger connected to target VM
5. Target VM: Windows kernel debugging target

✨ Features

🔧 Core Debugging Tools

• Session Management: Connection health monitoring, session recovery
• Command Execution: Validation, resilience, and performance optimization
• LLM Automation: Full execution control and breakpoint automation for AI-driven debugging
• Process Analysis: List, switch, and analyze kernel processes
• Thread Analysis: Thread enumeration, stack traces, and context switching
• Memory Analysis: Memory inspection, structure analysis, and search capabilities
• Kernel Analysis: Kernel objects, IDT, handles, and system structures

🚀 Performance & Reliability

• Network Optimization: Designed for VM based kernel debugging over network
• Connection Resilience: Automatic retry logic with exponential backoff
• Async Operations: Parallel command execution for better performance
• Result Caching: Caching with TTL for faster repeated operations
• Data Compression: Automatic compression for large outputs
• Session Recovery: State preservation and recovery for interrupted sessions

🛠️ Natural Language Hacking

• “Hide explorer.exe using EPROCESS unlink and PspCidTable Unlink”
• “Make OneDrive.exe appear to have no open handles”
• “Make notepad.exe resistance to termination and kill attempts”
• “Install invisible system call hooks that dont modify SSDT”
• “Hide network connections from netstat while keeping them active”
• “Make files invisible to directory enumeration but accessible by direct path”

🚀 Quick Start

Prerequisites

• Windows 10/11 (host machine)
• WinDbg (Windows Debugger) (Windows SDK)
• Python 3.10+ with Poetry
• Target Windows VM configured for kernel debugging
• MCP-compatible LLM client (Cursor, Claude Desktop, VS Code + Cline/Roo)
• (Optional) Visual Studio with C++ build tools

Installation

1. Get the WinDbg Extension DLL:

   You have two options:

   • Option 1: Download Pre-built DLL

     • Go to the Releases page and download the latest windbgmcpExt.dll for your platform.
     • Place the DLL in a known directory (you’ll load it from this path in WinDbg).

   • Option 2: Clone and Build from Source

     git clone https://github.com/NadavLor/windbg-ext-mcp.git
     cd windbg-ext-mcp/extension
     msbuild /p:Configuration=Release /p:Platform=x64
     

2. Load the extension in WinDbg:

   .load C:\path\to\windbgmcpExt.dll
   

3. Configure your LLM client:

   python install_client_config.py
   

4. Install and start the MCP server:

   poetry install
   

   Now either start the server via the LLM client or manually:

   poetry run python mcp_server/server.py
   

For first time debuggers

1. Configure target VM for kernel debugging

   # On target VM (as Administrator)
   bcdedit /debug on
   bcdedit /dbgsettings net hostip:YOUR_HOST_IP port:50000 key:YOUR_KEY
   shutdown /r /t 0
   

2. Connect WinDbg to target VM

   # On host machine
   windbg -k net:port=50000,key=YOUR_KEY
   

3. Load the WinDbg extension

   # In WinDbg command window
   .load C:\path\to\windbgmcpExt.dll
   

📖 Usage Examples

Basic Debugging Session

1. Start a debugging session

   # In Cursor chat
   debug_session(action="status")
   

2. List all processes in the kernel

   # In Cursor chat
   analyze_process(action="list")
   

3. Analyze a specific process

   # Copy process address from the list above
   analyze_process(action="info", address="0xffff8e0e481d7080")
   

4. Get memory information

   analyze_memory(action="read", address="0x1000", size="0x100")
   

5. Parallel command execution

   async_manager(action="parallel", commands=["version", "lm", "!process -1 0"])
   

6. Performance optimization

   performance_manager(action="set_level", level="aggressive")
   

7. Session recovery

   session_manager(action="capture")  # Save current state
   session_manager(action="recover", strategy="automatic")  # Recover if needed
   

Natural Language Debugging

You can also use natural language prompts in Cursor:

• “Show me all running processes in the kernel”
• “What’s the current thread’s stack trace?”
• “Analyze the memory at address 0x1000”
• “Help me understand this crash dump”
• “Set a breakpoint on nt!NtCreateFile and continue execution”
• “Step through the next 3 instructions and show me the registers”

⚙️ Configuration

Environment Variables

• DEBUG=true: Enable debug logging
• VERBOSE=true: Enable verbose logging
• OPTIMIZATION_LEVEL=aggressive: Set performance optimization level

Network Debugging Modes

• stable: Standard timeouts (reliable networks)
• unstable: Extended timeouts (unreliable networks)
• ultra_stable: Maximum timeouts (poor connections)

Timeout Categories

• quick: 5s (version, registers)
• normal: 15s (most commands)
• slow: 30s (stack traces, thread info)
• bulk: 60s (process lists, module lists)
• analysis: 120s (crash analysis, complex operations)

🛠️ Available Tools

Session Management

• debug_session: Get session status and metadata
• connection_manager: Manage connection resilience and health
• session_manager: Session recovery and state management

Command Execution

• run_command: Execute WinDbg commands with optimization
• run_sequence: Execute multiple commands in sequence
• breakpoint_and_continue: Set breakpoints and control execution in one step

Analysis Tools

• analyze_process: Process analysis and context switching
• analyze_thread: Thread analysis and stack traces
• analyze_memory: Memory inspection and structure analysis
• analyze_kernel: Kernel object and system analysis

Performance Tools

• performance_manager: Performance optimization control
• async_manager: Asynchronous command execution

Support Tools

• troubleshoot: Debugging assistance and diagnostics
• get_help: Tool documentation and examples

Debug Mode

Enable debug logging for troubleshooting:

# Set environment variable
set DEBUG=true

# Or modify config.py
DEBUG_ENABLED = True

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Microsoft WinDbg team for the debugging platform
• Anthropic for the Model Context Protocol
• FastMCP for the Python MCP framework

Happy kernel debugging! 🐛🔍