Metadata-Version: 2.4
Name: mcp-windbg
Version: 0.15.0
Summary: A Model Context Protocol server providing tools to analyze Windows crash dumps using WinDbg/CDB
Author-email: svnscha <sven.scharmentke@gmail.com>
Maintainer-email: svnscha <sven.scharmentke@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/svnscha/mcp-windbg
Project-URL: Repository, https://github.com/svnscha/mcp-windbg
Project-URL: Issues, https://github.com/svnscha/mcp-windbg/issues
Project-URL: Changelog, https://github.com/svnscha/mcp-windbg/blob/main/CHANGELOG.md
Keywords: windbg,cdb,mcp,llm,crash-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Environment :: Console
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.26.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: starlette>=0.52.1
Requires-Dist: uvicorn>=0.42.0
Provides-Extra: test
Requires-Dist: pytest>=9.0.2; extra == "test"
Requires-Dist: pyyaml>=6.0.2; extra == "test"
Requires-Dist: coverage[toml]>=7.6; extra == "test"
Dynamic: license-file

# MCP Server for WinDbg Crash Analysis

[![CI](https://github.com/svnscha/mcp-windbg/actions/workflows/ci.yml/badge.svg)](https://github.com/svnscha/mcp-windbg/actions/workflows/ci.yml)
[![Docs](https://github.com/svnscha/mcp-windbg/actions/workflows/pages.yml/badge.svg)](https://svnscha.github.io/mcp-windbg/)
[![PyPI](https://img.shields.io/pypi/v/mcp-windbg)](https://pypi.org/project/mcp-windbg/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
![Platform: Windows](https://img.shields.io/badge/platform-Windows-0078D6)
![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB)

A Model Context Protocol server that bridges AI models with WinDbg for crash dump analysis and remote debugging.

<!-- mcp-name: io.github.svnscha/mcp-windbg -->

## Overview

This MCP server integrates with [CDB](https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/opening-a-crash-dump-file-using-cdb) to enable AI models to analyze Windows crash dumps and connect to remote debugging sessions using WinDbg/CDB.

## What is this?

An AI-powered tool that bridges LLMs with WinDbg for crash dump analysis and live debugging. Execute debugger commands through natural language queries like *"Show me the call stack and explain this access violation"*.

## What This is Not

Not a magical auto-fix solution. It's a Python wrapper around CDB that leverages LLM knowledge to assist with debugging.

## Usage Modes

- **Crash Dump Analysis**: Examine Windows crash dumps
- **Live Debugging**: Connect to remote debugging targets
- **Directory Analysis**: Process multiple dumps for patterns

## Quick Start

### Prerequisites
- Windows with [Debugging Tools for Windows](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/) or [WinDbg from Microsoft Store](https://apps.microsoft.com/detail/9pgjgd53tn86).
- Python 3.10 or higher
- Any MCP-compatible client (GitHub Copilot, Claude Desktop, Cline, Cursor, Windsurf etc.)
- Configure MCP server in your chosen client

> [!TIP]
> In enterprise environments, MCP server usage might be restricted by organizational policies. Check with your IT team about AI tool usage and ensure you have the necessary permissions before proceeding.

### Installation
```bash
pip install mcp-windbg
```

## Transport Options

The MCP server supports multiple transport protocols:

| Transport | Description | Use Case |
|-----------|-------------|----------|
| `stdio` (default) | Standard input/output | Local MCP clients like VS Code, Claude Desktop |
| `streamable-http` | Streamable HTTP | Modern HTTP clients with bidirectional streaming |

### Starting with Different Transports

**Standard I/O (default):**
```bash
mcp-windbg
# or explicitly
mcp-windbg --transport stdio
```

**Streamable HTTP:**
```bash
mcp-windbg --transport streamable-http --host 127.0.0.1 --port 8000
```
Endpoint: `http://127.0.0.1:8000/mcp`

### Command Line Options

```
--transport {stdio,streamable-http}  Transport protocol (default: stdio)
--host HOST                              HTTP server host (default: 127.0.0.1)
--port PORT                              HTTP server port (default: 8000)
--cdb-path PATH                          Custom path to cdb.exe
--symbols-path PATH                      Custom symbols path
--filter-script PATH                     Python script with process_input/process_output tool text hooks
--timeout SECONDS                        Command timeout (default: 30)
--verbose                                Enable verbose output
```

### Filter Script Hooks

Use `--filter-script` to load a small Python helper that can rewrite tool text only. The script never sees the full MCP JSON-RPC envelope, which keeps the hook surface smaller and avoids protocol interference.

The script may define either or both of these functions:

```python
def process_input(text, context):
    return text


def process_output(text, context):
    return text
```

- `process_input` is applied to string-valued tool arguments before the tool handler runs.
- `process_output` is applied to `TextContent.text` values returned by tools before they go back to the client.
- `text` is always a plain `str`.
- `context` includes `hook`, `tool_name`, `transport`, and `call_id`.
- Input callbacks also receive `argument_path` such as `$.command` or `$.payload.notes[0]`.
- Output callbacks also receive `content_index` for the returned text item.
- `call_id` is stable for the full lifetime of one tool invocation, so script writers can correlate input and output for the same call.
- A hook may return `None` to leave the text unchanged, or return a replacement string.

Example redaction filter:

```python
def process_input(text, context):
    if context["tool_name"] == "run_windbg_cmd" and context["argument_path"] == "$.command":
        return text.replace("user@example.com", "[redacted-email]")
    return text


def process_output(text, context):
    return text.replace("user@example.com", "[redacted-email]")
```

Start the server with the filter enabled:

```bash
mcp-windbg --filter-script C:\filters\pii_redaction.py
```

The script runs in-process with the server. Treat it as trusted code.


## Configuration for Visual Studio Code

To make MCP servers available in all your workspaces, use the global user configuration:

1. Press `F1`, type `>` and select **MCP: Open User Configuration**.
2. Paste the following JSON snippet into your user configuration:

```json
{
    "servers": {
        "mcp_windbg": {
            "type": "stdio",
            "command": "python",
            "args": ["-m", "mcp_windbg"],
            "env": {
                "_NT_SYMBOL_PATH": "SRV*C:\\Symbols*https://msdl.microsoft.com/download/symbols"
            }
        }
    }
}
```

This enables MCP Windbg in any workspace, without needing a local `.vscode/mcp.json` file.

To enable a filter script, add it to the args:

```json
"args": ["-m", "mcp_windbg", "--filter-script", "C:\\filters\\pii_redaction.py"]
```

### HTTP Transport Configuration

For scenarios where you need to run the MCP server separately (e.g., remote access, shared server, or debugging the server itself), you can use the HTTP transport:

**1. Start the server manually:**
```bash
python -m mcp_windbg --transport streamable-http --host 127.0.0.1 --port 8000
```

**2. Configure VS Code to connect via HTTP:**
```json
{
    "servers": {
        "mcp_windbg_http": {
            "type": "http",
            "url": "http://localhost:8000/mcp"
        }
    }
}
```

> **Workspace-specific and alternative configuration**: See the [client configuration guide](https://svnscha.github.io/mcp-windbg/reference/clients/) for details on configuring Claude Desktop, Copilot CLI, and other clients, or for workspace-only setup.

Once configured, restart your MCP client and start debugging:

```
Analyze the crash dump at C:\dumps\app.dmp
```

## MCP Compatibility

This server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), making it compatible with any MCP-enabled client:

The beauty of MCP is that you write the server once, and it works everywhere. Choose your favorite AI assistant!

### Tools

| Tool | Purpose | Use Case |
|------|---------|----------|
| [`list_windbg_dumps`](https://svnscha.github.io/mcp-windbg/reference/tools/#list_windbg_dumps) | List crash dump files | Discovery and batch analysis |
| [`open_windbg_dump`](https://svnscha.github.io/mcp-windbg/reference/tools/#open_windbg_dump) | Analyze crash dumps | Initial crash dump analysis |
| [`close_windbg_dump`](https://svnscha.github.io/mcp-windbg/reference/tools/#close_windbg_dump) | Cleanup dump sessions | Resource management |
| [`open_windbg_remote`](https://svnscha.github.io/mcp-windbg/reference/tools/#open_windbg_remote) | Connect to remote debugging | Live debugging sessions |
| [`close_windbg_remote`](https://svnscha.github.io/mcp-windbg/reference/tools/#close_windbg_remote) | Cleanup remote sessions | Resource management |
| [`run_windbg_cmd`](https://svnscha.github.io/mcp-windbg/reference/tools/#run_windbg_cmd) | Execute WinDbg commands | Custom analysis and investigation |
| [`send_ctrl_break`](https://svnscha.github.io/mcp-windbg/reference/tools/#send_ctrl_break) | Break into a running target | Interrupt execution during live debugging |

## Documentation

**[Documentation](https://svnscha.github.io/mcp-windbg/)**

| Topic | Description |
|-------|-------------|
| **[Getting Started](https://svnscha.github.io/mcp-windbg/getting-started/)** | Quick setup and first crash dump analysis |
| **[Use cases](https://svnscha.github.io/mcp-windbg/scenarios/)** | Analyze a dump, debug a remote target, triage many dumps |
| **[Command-line options](https://svnscha.github.io/mcp-windbg/reference/cli/)** | Every CLI flag, transports, and filter hooks |
| **[Tools Reference](https://svnscha.github.io/mcp-windbg/reference/tools/)** | The MCP tools and their parameters |
| **[Client configuration](https://svnscha.github.io/mcp-windbg/reference/clients/)** | VS Code, Claude Desktop, Copilot CLI, pip, and source |
| **[Troubleshooting](https://svnscha.github.io/mcp-windbg/troubleshooting/)** | Common issues and solutions |

## Examples

### Crash Dump Analysis

> Analyze this heap address with !heap -p -a 0xABCD1234 and check for buffer overflow"

> Execute !peb and tell me if there are any environment variables that might affect this crash"

> Run .ecxr followed by k and explain the exception's root cause"

### Remote Debugging

> "Connect to tcp:Port=5005,Server=192.168.0.100 and show me the current thread state"

> "Send CTRL+BREAK to the live session, then dump all thread stacks with ~*k"

> "Check for timing issues in the thread pool with !runaway and !threads"

> "Show me all threads with ~*k and identify which one is causing the hang"

## Blog

Read about the development journey: [The Future of Crash Analysis: AI Meets WinDbg](https://svnscha.de/posts/ai-meets-windbg/)

### Links

- [Reddit: I taught Copilot to analyze Windows Crash Dumps](https://www.reddit.com/r/programming/comments/1kes3wq/i_taught_copilot_to_analyze_windows_crash_dumps/)
- [Hackernews: AI Meets WinDbg](https://news.ycombinator.com/item?id=43892096)

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=svnscha/mcp-windbg&type=Date)](https://www.star-history.com/#svnscha/mcp-windbg&Date)

## License

MIT
