etw-mcp

An MCP server that lets AI coding assistants analyze Windows WPR/ETW traces (.etl files). Load a trace, then ask questions in natural language — the server uses a self-contained .NET sidecar by default (auto-downloaded on first use), with a fast in-process ETW path and xperf.exe as fallbacks.

[!IMPORTANT] Personal hobby project — not endorsed by Microsoft.

This repository is a personal side project. It is not an official Microsoft product, is not affiliated with or endorsed by Microsoft, and carries no warranty or support guarantee. Use at your own risk.

New here? Start with GETTING-STARTED.md for a 30-minute clone-to-first-query walkthrough, then ARCHITECTURE.md for the cross-repo dataflow.

Works with any Windows performance trace: networking (tcpip.sys, NDIS, NIC drivers, HTTP.sys), kernel (DPCs, ISRs, context switches), and application workloads.

Quick Install

This example pins v0.9.3. Install uv and the Windows Performance Toolkit, then create a persistent, versioned environment once:

winget install astral-sh.uv
winget install --id Microsoft.WindowsADK --override "/features OptionId.WindowsPerformanceToolkit /quiet"

$install = Join-Path $env:USERPROFILE 'MCP\etw-mcp-0.9.3'
New-Item -ItemType Directory -Force -Path (Split-Path $install) | Out-Null
uv venv --python 3.11 $install

# Optional: use a private, corporate, or approved package mirror for dependencies.
# $env:UV_INDEX_URL = 'https://your-package-index.example/simple'
uv pip install --python "$install\Scripts\python.exe" 'https://github.com/nijosmsft/etw-mcp/releases/download/v0.9.6/etw_mcp-0.9.6-py3-none-any.whl'

When UV_INDEX_URL is unset, uv uses its default public package index. Setting it before uv pip install changes dependency resolution only; the etw-mcp wheel still comes from the explicit GitHub URL. Omit or unset it to use uv's default index. After installation, do not add UV_INDEX_URL to the MCP runtime config unless your environment independently requires it.

A persistent environment is recommended because MCP clients impose initialization deadlines. uv run --no-project --with <wheel> ... is useful only for an ad hoc smoke test and is not recommended for MCP configuration; it may recreate or materialize the dependency environment at every server launch even when downloads are cached.

Configure the client to launch the installed Python directly. JSON does not expand %USERPROFILE%; replace YOURNAME (or the entire command) with the actual absolute path. The top-level key is mcpServers for Claude Code, Claude Desktop, GitHub Copilot CLI, and Cursor, while VS Code uses servers; see Setup for paths. The symbol environment example is optional.

{
  "mcpServers": {
    "etw-trace-analyzer": {
      "type": "stdio",
      "command": "C:\\Users\\YOURNAME\\MCP\\etw-mcp-0.9.3\\Scripts\\python.exe",
      "args": ["-m", "etw_analyzer.server"],
      "env": {
        "_NT_SYMBOL_PATH": "srv*C:\\symbols*https://msdl.microsoft.com/download/symbols"
      }
    }
  }
}

The first load_trace call separately auto-downloads the matching .NET sidecar (~40 MB) into %LOCALAPPDATA%\etw-mcp\sidecar\v0.9.3\ and may pull 200-500 MB of PDBs to C:\symbols. This sidecar bootstrap is separate from Python dependency installation. Set ETW_MCP_NO_AUTO_DOWNLOAD=1 to skip the sidecar fetch.

Features

• Auto-summary — one-call comprehensive analysis: system config, per-CPU utilization, hot functions, symbol status, DPC health
• CPU sampling — hot functions by module, process, or call stack
• Per-CPU breakdown — utilization per logical processor, identify hot/idle/saturated CPUs
• Per-CPU filtering — drill into what's running on a specific CPU (e.g. "what's saturating CPU 0?")
• Trace comparison — diff two traces to find regressions (hot functions, modules, or per-CPU utilization)
• DPC/ISR analysis — duration histograms, per-CPU distribution, watchdog risk detection
• Lock contention — spinlock contention from ReadyThread/context switch stacks
• Symbol resolution — automatic PDB download from symbol servers
• Call stacks — butterfly stacks with caller/callee relationships, recursive stack walks, and WPA-style chain exports
• System info — CPU model, NIC details, memory, disk config from trace metadata
• Process info — running processes, command lines, loaded driver versions
• Disk I/O — per-file I/O summary to rule out storage bottlenecks
• Network flows and sockets — TCP/UDP throughput, per-flow summaries, retransmits, socket lifecycle, and AFD batching
• Packet capture analysis — decode NDIS PacketCapture frame bytes from WPR/pktmon-style ETLs, including 5-tuples, timelines, and Send→Recv latency estimates
• Export — save analysis to markdown for sharing via email
• Caching — parquet-based disk cache for instant reload, parallel xperf extraction

Installation

Windows only — this server uses Windows ETW APIs (advapi32, tdh, dbghelp).

# 1. Install prerequisites — skip any you already have
winget install astral-sh.uv              # Python package manager
winget install --id Microsoft.WindowsADK --override "/features OptionId.WindowsPerformanceToolkit /quiet"
                                         # Recommended — provides xperf for fallback and full analysis coverage.
                                         # NOTE: do NOT use Microsoft.WindowsSDK — it is not a valid winget package ID.
                                         # The --override flag installs just the ~150 MB WPT feature instead of the full ~5 GB ADK.

# 2. Create a persistent environment for v0.9.3
$install = Join-Path $env:USERPROFILE 'MCP\etw-mcp-0.9.3'
New-Item -ItemType Directory -Force -Path (Split-Path $install) | Out-Null
uv venv --python 3.11 $install

# 3. Optional: select a private, corporate, or approved dependency mirror
# $env:UV_INDEX_URL = 'https://your-package-index.example/simple'

# 4. Install the pinned release once
uv pip install --python "$install\Scripts\python.exe" 'https://github.com/nijosmsft/etw-mcp/releases/download/v0.9.6/etw_mcp-0.9.6-py3-none-any.whl'

# 5. Optional smoke test (Ctrl+C to stop)
& "$install\Scripts\python.exe" -m etw_analyzer.server

• uv downloads Python when needed and creates the requested virtual environment. No separate Python installation is required.
• Persistent environment — MCP clients impose initialization deadlines. Installing dependencies once avoids per-launch environment materialization; point the client directly at $install\Scripts\python.exe.
• Custom dependency index — when UV_INDEX_URL is unset, uv uses its default public package index. Environments that require a private, corporate, or approved mirror can set $env:UV_INDEX_URL = 'https://your-package-index.example/simple' before uv pip install. This affects dependency resolution only, not the explicit GitHub wheel URL. Omit or unset it for uv's default index, and do not put it in the completed install's MCP runtime config unless independently required.
• Release wheel — v0.9.3 is pinned above. For another version, use the .whl asset URL from its GitHub release and a separate versioned environment.
• .NET sidecar (default; auto-bootstrapped) — etw-extract.exe is a self-contained .NET binary (~40 MB, no .NET install required) that decodes ETL files faster than the in-process path and frees the Python process from holding the full event buffer. On the first trace load, the wheel auto-fetches the matching version from the GitHub release and caches v0.9.3 at %LOCALAPPDATA%\etw-mcp\sidecar\v0.9.3\. This is separate from Python dependency installation. Set ETW_MCP_NO_AUTO_DOWNLOAD=1 to disable the fetch (the server then falls back to the native consumer) or set ETW_MCP_DOTNET_SIDECAR to pin a manually-built binary. See dotnet/README.md for build instructions and src/etw_analyzer/native/SIDECAR.md for the supervisor plumbing.
• Native ETW consumer (fallback when sidecar is unavailable) — the server decodes ETL files in-process via OpenTraceW/tdh.dll. This path is enough to start the MCP server and run the core native analysis tools on recent Windows builds and is the automatic fallback when auto-bootstrap is blocked.
• Kernel symbols need an MSFZ-capable dbghelp — published Windows OS PDBs for kernel modules can be MSFZ-compressed. The inbox C:\Windows\System32\dbghelp.dll on 10.0.26100-era systems cannot read those PDBs; install Debugging Tools for Windows / WinDbg (known-good dbghelp.dll 10.0.29507+) and place dbghelp.dll + symsrv.dll in C:\Debuggers, or set ETW_MCP_DBGHELP=<full path to dbghelp.dll> and optionally ETW_MCP_SYMSRV=<full path to symsrv.dll>.
• xperf.exe / Windows Performance Toolkit — installed as part of the Windows SDK. Recommended for complete results because it enables fallback extraction, richer WPA-derived stack views, xperf-only tools such as pool analysis, and older Windows builds where the native bindings can't load. Expected location: C:\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit\xperf.exe

Upgrading

Create a side-by-side environment for the new release rather than mutating an environment used by a running MCP server:

$newInstall = Join-Path $env:USERPROFILE 'MCP\etw-mcp-NEW_VERSION'
New-Item -ItemType Directory -Force -Path (Split-Path $newInstall) | Out-Null
uv venv --python 3.11 $newInstall
uv pip install --python "$newInstall\Scripts\python.exe" 'NEW_RELEASE_WHEEL_URL'

Update the MCP config's command to the new environment's python.exe, then restart the client. After no MCP config references v0.9.3, optionally remove only its old directory: Remove-Item -LiteralPath (Join-Path $env:USERPROFILE 'MCP\etw-mcp-0.9.3') -Recurse -Force.

Setup

Configure your AI assistant to use the server:

Claude Code

Add to your .mcp.json (project root or ~/.claude/.mcp.json):

{
  "mcpServers": {
    "etw-trace-analyzer": {
      "type": "stdio",
      "command": "C:\\Users\\YOURNAME\\MCP\\etw-mcp-0.9.3\\Scripts\\python.exe",
      "args": ["-m", "etw_analyzer.server"],
      "env": {
        "_NT_SYMBOL_PATH": "srv*C:\\symbols*https://msdl.microsoft.com/download/symbols"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json (workspace) or %APPDATA%\Code\User\mcp.json (user-scoped):

Note: VS Code uses servers as the top-level key, NOT mcpServers. Pasting an mcpServers block into a VS Code config silently does nothing — the server will not appear in Copilot. Every other MCP client documented here uses mcpServers.

{
  "servers": {
    "etw-trace-analyzer": {
      "type": "stdio",
      "command": "C:\\Users\\YOURNAME\\MCP\\etw-mcp-0.9.3\\Scripts\\python.exe",
      "args": ["-m", "etw_analyzer.server"],
      "env": {
        "_NT_SYMBOL_PATH": "srv*C:\\symbols*https://msdl.microsoft.com/download/symbols"
      }
    }
  }
}

Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json (top-level key: mcpServers):

{
  "mcpServers": {
    "etw-trace-analyzer": {
      "type": "stdio",
      "command": "C:\\Users\\YOURNAME\\MCP\\etw-mcp-0.9.3\\Scripts\\python.exe",
      "args": ["-m", "etw_analyzer.server"],
      "env": {
        "_NT_SYMBOL_PATH": "srv*C:\\symbols*https://msdl.microsoft.com/download/symbols"
      }
    }
  }
}

GitHub Copilot CLI

Add to %USERPROFILE%\.copilot\mcp-config.json (top-level key: mcpServers):

{
  "mcpServers": {
    "etw-trace-ana