profiler-mcp
by Lagooneng
README.md
# profiler-mcp
**English** | [한국어](README.ko.md)
An MCP server that measures where a running C++ process spends its time: the functions using CPU, time spent waiting,
and GPU usage, aggregated down to the function level with PDBs. The target program does not need to be modified or
restarted. Tools for Unreal Engine are included.
## Requirements
| Item | Install |
|---|---|
| Windows 10 or later (64-bit) | — |
| uv | `winget install astral-sh.uv` |
| msdia140.dll | Visual Studio's "Desktop development with C++" workload |
| Very Sleepy (optional) | `winget install codersnotes.VerySleepy` — only needed for `quick_sample` |
| Unreal Engine (optional) | The `ue_` tools are enabled when it is installed |
## Install (Claude Code plugin)
```
/plugin marketplace add Lagooneng/profiler-mcp
/plugin install profiler-mcp@profiler-marketplace
```
## What to measure with
| What you want to know | Use |
|---|---|
| What is heavy right now, quickly | `quick_sample` → `top_functions` / `call_tree` |
| How many ms, and how much a fix saved | `capture_start` / `capture_stop` before and after → `compare` |
| Which thread is busy | `capture` → `threads` |
| What it is waiting on | `capture_start(mode='cpu+wait')` → `wait_summary` |
| Whether the GPU is the bottleneck | `capture` → `gpu_usage` |
| When frames hitch | `capture_start(gpu=True)` → `gpu_frames` |
| Unreal: engine scopes, frames, render passes | `ue_frames`, `ue_top_timers`, `ue_timer_callees` |
- `quick_sample` samples one thread for a few seconds without administrator rights. The target slows down noticeably
while it runs, so use **only the ratios and ranking**.
It works by running [Very Sleepy](https://github.com/VerySleepy/verysleepy) (GPL-2.0) and reading its result file.
Because of that license, this repository does not include its executable or code; it uses the copy you install yourself.
- `capture_start` / `capture_stop` record the whole system with ETW. A UAC prompt appears once for start and once for stop.
- For Unreal projects, Unreal Insights traces (the `ue_` tools) are the default. They need no administrator rights.
## Tools
| Tool | What it does |
|---|---|
| `status` | Tool paths, capture in progress, storage |
| `capture_start` / `capture_stop` / `capture_cancel` | Start an ETW capture · stop and save · discard |
| `quick_sample` | Sample one thread without administrator rights |
| `list_traces` / `delete_trace` | Manage saved traces |
| `processes` / `threads` | CPU usage per process · per thread |
| `trace_info` | Capture quality (stack coverage, modules that had PDBs) |
| `top_functions` / `callers_callees` / `call_tree` | Time per function, call relationships |
| `compare` | Per-function change between two captures |
| `wait_summary` | Waiting time by reason · by the thread that woke it |
| `gpu_frames` / `gpu_usage` | Frame presentation intervals, GPU usage per process |
| `ue_trace_commands` / `ue_list_traces` / `ue_delete_trace` | Record and manage Insights traces |
| `ue_frames` / `ue_threads` | Frame times, thread list |
| `ue_top_timers` / `ue_timer_callees` | Time per engine scope (CPU threads, GPU queues) |
| `ue_sampling_window` | Where an ETW capture and an Insights trace overlap |
The [`profile-report`](skills/profile-report/SKILL.md) skill is installed with the plugin: the format for reporting
results and the checks to run before reporting.
## Good to know
- **The UAC prompt shows "Windows Performance Recorder".** Any other name is not a prompt from this server.
- **An ETW capture records the whole system.** The trace contains the names and stacks of other processes. Take care when sharing the file.
- **A capture keeps running independently of this server.** Once started, stop it or cancel it.
- **Modules without a PDB are grouped as `[module name]`.** Symbols for the kernel and Windows system DLLs are not supported.
- **Storage**: a single capture overwrites its oldest part at 10 GB, and when saved traces exceed 20 GB in total the least recently used are deleted.
## Environment variables
| Variable | Meaning |
|---|---|
| `PROFILER_CACHE_DIR` | Where traces and PDB copies are kept (default `%LOCALAPPDATA%\profiler-mcp`) |
| `PROFILER_MAX_CAPTURE_GB` | Size cap for a single capture (default `10`, `0` for no cap) |
| `PROFILER_TRACES_CAP_GB` | Cap on the total size of saved traces (default `20`, `0` to never clean up) |
| `PROFILER_SYMBOL_DIRS` | Folders of PDBs that are never rebuilt (separated by `;`) |
| `PROFILER_WPR_PATH` / `PROFILER_MSDIA_PATH` / `PROFILER_SLEEPY_PATH` / `PROFILER_UNREAL_INSIGHTS_PATH` | Paths to tools that are not found in their default location |
| `PROFILER_SKIP_BOOT_CHECK` | `1` skips the check that an ETW capture and an Insights trace come from the same boot |
## Tests
```
uv run python tests\test_units.py
uv run python tests\test_mcp_e2e.py <process name> [trace name] [--capture]
uv run python tests\test_unreal_insights.py [trace name]
```
`--capture` runs a real capture, so the UAC prompt appears twice.