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.

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):

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

Or without installing, using uv:

{
  "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

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