WinDbg‑ext‑MCP

WinDbg extension + Python MCP server. Lets MCP‑compatible clients (Cursor, Claude, VS Code + Cline/Roo) drive WinDbg with clean, validated commands. Kernel‑first; user‑mode works too.

Contents

• Quick Start
• Architecture
• Usage Examples
• What’s Here
• Sanity Check
• Troubleshooting
• Configuration
• Tested With
• Notes

Quick Start

Prereqs

• Windows 10/11
• WinDbg (Windows SDK “Debugging Tools for Windows”)
• Visual Studio Build Tools (C++)
• Python 3.10+ and Poetry 2.x

Build the extension (Developer PowerShell for VS):

msbuild extension\windbgmcpExt.sln /p:Configuration=Release /p:Platform=x64

Load in WinDbg:

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

Install and run the MCP server (in root directory):

poetry install
poetry run selftest
poetry run mcp --list-tools
poetry run mcp

Architecture

MCP Client (stdio)    Python MCP Server (stdio)    WinDbg Extension (named pipe)    WinDbg/Target
                             FastMCP                      \\.\pipe\windbgmcp                   Kernel/User

• The extension hosts a named‑pipe server and executes WinDbg commands safely.
• The Python server validates inputs, resolves timeouts, and exposes tools to MCP clients.

Usage Examples

General (natural language prompts)

• “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”

Rootkit behavior (research‑only)

• “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”

Note: These are for lawful, defensive research in controlled test labs only.

Available Tools

• debug_session: session status and metadata
• connection_manager: connection health and resilience controls
• session_manager: capture/restore debugging context
• run_command: execute a WinDbg command with validation/timeout handling
• run_sequence: execute multiple commands in order
• breakpoint_and_continue: set a breakpoint and continue execution
• analyze_process: process enumeration, info, and context switching
• analyze_thread: thread info and stack traces
• analyze_memory: memory display, typed structures, searches
• analyze_kernel: kernel objects and system analysis
• performance_manager: optimization controls and performance report
• async_manager: parallel execution and async task stats
• troubleshoot: quick diagnostics and guidance
• get_help: list tools and usage tips
• test_windbg_communication: pipe connectivity test
• network_debugging_troubleshoot: network debugging issue checks

What’s Here

• extension/: C++ WinDbg extension. Named pipe \\.\pipe\windbgmcp. Exports: help, objecttypes, hello, mcpstart, mcpstop, mcpstatus.
• mcp_server/: Python MCP server using FastMCP with modular tools (session, execution, analysis, performance, support).
• install_client_config.py: Optional helper to write MCP client configs (Cursor/Claude/VS Code).

MCP Client Config (optional)

Writes/updates MCP client configuration so your client can discover and launch this server.

Supported clients

• Cursor, Claude Desktop, VS Code (Cline / Roo Code), Windsurf (Codeium)

Commands (run from repo root)

# Dry run (preview changes)
python install_client_config.py --install --dry-run

# Install configs for detected clients
python install_client_config.py --install

# Uninstall (revert changes)
python install_client_config.py --uninstall

# Self-test only (no writes)
python install_client_config.py --test

Notes

• The script detects your OS and only touches clients it finds installed.
• It uses your current Python (sys.executable) to run the server and writes a stdio MCP config.
• Install mode runs a quick server import test first; fix any errors before proceeding.

Sanity Check (no target required)

Self‑test stubs the transport and validates the protocol.

poetry run selftest

Expected: “Selftest OK”.

Troubleshooting

• Extension won’t load:
  • Path or arch mismatch. Use x64 WinDbg with the x64 DLL.
  • If linking fails, install Windows SDK Debugging Tools.
• Pipe connection errors:
  • The extension hosts the server. Ensure it’s started (mcpstart) and \\.\pipe\windbgmcp exists.
• Slow/spotty results:
  • Fix symbol paths, bump timeouts for remote/VM targets, and scope commands.

Configuration

• DEBUG=true enables verbose logs in the Python server.
• Timeouts auto‑resolve per command type. See mcp_server/config.py for categories.

Tested With

• Windows 11, MSVC v143, Windows SDK 10.0.22621.0
• Python 3.13, Poetry 2.1
• FastMCP 2.5.1, pywin32 310

Notes

• Build the DLL, run the server, load the extension. If WinDbg can’t load, the path is wrong or the arch doesn’t match. Fix that first.