# windows-debug-mcp

A **read-only** MCP server for diagnosing Windows crashes, stability problems and
gaming performance.

It reads event logs, crash dumps, error reports, hardware and driver inventory,
performance counters, power configuration and the registry settings that matter
for games — and it has no code that can change any of them.

## The read-only guarantee

This is the whole design constraint, so it is enforced in four independent
layers rather than by convention:

1. **No mutating code exists.** The package never imports a write API. Files are
   opened in binary-read mode, registry keys with `KEY_READ`, and processes are
   spawned with a fixed argument vector and `shell=False`.
2. **No passthrough.** No tool accepts a command, script or argument that is
   executed as code. Every PowerShell fragment that runs ships inside the
   package; caller-supplied values are passed to it as JSON in an environment
   variable and are only ever used as values.
3. **Allowlisted cmdlets.** Before a script runs it is parsed and rejected
   unless every cmdlet in it is on a read-only allowlist. External executables
   are checked including their arguments — `powercfg /query` is allowed,
   `powercfg /setactive` is not.
4. **Deny patterns.** A final scan rejects redirection, `Invoke-Expression`,
   `Add-Type`, `.Delete()`, `reg add`, shell escapes and environment mutation,
   even if they would otherwise slip past the allowlist.

Layers 3 and 4 run on **every** invocation, so a script edited on disk after
installation is still rejected.

You do not have to take this on faith. The `verify_read_only_guarantees` tool
scans the installed source and reports what it found:

```
> verify_read_only_guarantees
{
  "clean": true,
  "summary": "No write APIs, mutating cmdlets or shell escapes found in the installed source.",
  "findings": []
}
```

The same audit runs as a test (`tests/test_safety.py`), along with about forty
cases asserting that mutating scripts and commands are refused.

## Install

Requires Python 3.10+ on Windows 10 or 11.

```powershell
git clone https://github.com/emyk/windows-mcp
cd windows-mcp
pip install .
```

Then register it with your MCP client. For Claude Desktop
(`%APPDATA%\Claude\claude_desktop_config.json`) or Claude Code
(`.mcp.json`):

```json
{
  "mcpServers": {
    "windows-debug": {
      "command": "windows-debug-mcp"
    }
  }
}
```

Or without installing, using [uv](https://docs.astral.sh/uv/):

```json
{
  "mcpServers": {
    "windows-debug": {
      "command": "uvx",
      "args": ["--from", "C:\\path\\to\\windows-mcp", "windows-debug-mcp"]
    }
  }
}
```

Run unelevated unless you need the Security event log or `bcdedit` output —
everything else works as a normal user.

## Tools

### Crashes and the event log

| Tool | What it gives you |
| --- | --- |
| `get_crash_history` | Every critical and error event from the System and Application logs over a window, with the known ones explained: bug checks, unexpected restarts, WHEA hardware errors, display driver resets, disk and NTFS errors, application crashes and hangs |
| `query_event_log` | Any log, filtered by time, severity, event ID, provider or message text |
| `list_event_logs` | Which logs exist and how many records they hold |
| `list_crash_dumps` | Kernel minidumps, `MEMORY.DMP`, live kernel reports and application dumps |
| `inspect_crash_dump` | Parses the dump header. For a kernel dump: the stop code, its four parameters and what they mean. For an application dump: the exception code, the faulting address and **the module that address belongs to** |
| `list_error_reports` / `read_error_report` | Windows Error Reporting entries — the faulting app, module, offset and exception code, which survive even when no dump was kept |
| `get_pagefile_and_dump_settings` | Why a dump was never written |
| `get_reliability_history` | The data behind Reliability Monitor |
| `get_boot_performance` | Boot and shutdown timings, and what specifically slowed them |

`inspect_crash_dump` reads only header structures, so it returns in
milliseconds even on a multi-gigabyte `MEMORY.DMP`. It also flags overlay and
anti-cheat modules loaded into a crashed process — Steam overlay, Discord,
RivaTuner, ShadowPlay, EAC, BattlEye and friends — because "disable the overlay"
resolves a large share of game crashes.

### Hardware and drivers

`get_system_overview`, `get_gpu_info`, `get_display_info`, `get_memory_modules`,
`get_storage_health`, `list_drivers`, `list_problem_devices`, `get_temperatures`.

`get_memory_modules` calls out modules running below their rated speed or at
mismatched speeds — the usual explanation for `MEMORY_MANAGEMENT` and
`WHEA_UNCORRECTABLE_ERROR`. `get_storage_health` returns wear level, power-on
hours and read errors from the drive's own reliability counters.
`list_problem_devices` decodes Device Manager codes, so a GPU that has fallen
over reads as "Code 43: Windows stopped this device because it reported
problems" rather than as a number.

### Performance

`get_performance_snapshot`, `list_processes`, `get_startup_programs`,
`list_services`, `get_power_configuration`, `get_sleep_states`,
`get_network_configuration`.

The performance snapshot reports the numbers that explain stutter rather than
throughput: DPC and interrupt time, processor queue length, hard page faults,
disk queue depth and per-engine GPU utilisation. Counters are read through the
locale-independent CIM classes, so it works on non-English installations where
counter paths are translated.

### Settings

`get_gaming_settings`, `get_per_application_graphics_settings`,
`get_security_mitigations`, `get_installed_software`, `get_windows_updates`,
`read_registry_key`, `read_registry_value`.

`get_gaming_settings` covers Game Mode, Game Bar and background recording,
hardware-accelerated GPU scheduling, multiplane overlay, `TdrDelay`, variable
refresh rate and Auto HDR, the multimedia scheduler's reservations,
`Win32PrioritySeparation` and power throttling. Each value is explained, and
"not set" is distinguished from "set to zero" — most of these keys are absent by
default, so the difference matters.

`get_security_mitigations` reports VBS, memory integrity (HVCI) and the
speculative-execution mitigation overrides, which is where "everything got
slower after an update" usually leads.

### Meta

`collect_diagnostic_snapshot` runs the common starting set in one call, with
each section independent so one unavailable data source does not lose the rest.
`verify_read_only_guarantees` audits the server's own source.
`get_server_status` reports whether the Windows data sources are reachable.

Two prompts, `diagnose_blue_screen` and `diagnose_game_stutter`, lay out an
investigation order.

## What it deliberately does not do

* **It cannot change anything.** When a setting should change, it tells you
  which one and leaves you to apply it.
* **No stack analysis.** Reading the call stack out of a dump needs WinDbg and
  symbol resolution. This server gives you the stop code, the parameters and the
  faulting module, which is usually enough to know where to look next.
* **`Win32_Product` is never enumerated.** Doing so triggers an MSI consistency
  check that can reconfigure installed products, which would not be read-only.
  Installed software is read from the uninstall registry keys instead.
* **No tracing.** Starting an ETW session is a write, so boot and shutdown
  timings come from the logs Windows already keeps.
* **Environment variables are not exposed**, since they routinely carry tokens.

## Development

```bash
pip install -e ".[dev]"
pytest
```

The test suite runs on any platform: the Windows-only paths are exercised
through synthetic dumps and error reports, and the read-only guard is tested
directly.

## Licence

MIT