livedbg-mcp
Enables live debugging and inspection of running C++ processes, including attaching to processes, looking up symbols and type layouts, evaluating expressions with natvis support, reading and writing memory, setting breakpoints, stepping, inspecting stacks and locals, and working with Unreal-specific debug information.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
livedbg-mcp
English | 한국어
An MCP server that reads and debugs a running C++ process (a development build with PDBs). It drives execution and shows values through cdb (with natvis), and looks up symbols and types quickly through DIA.
The core is generic C++. For Unreal processes it loads
Unreal.natvisautomatically.Several sessions can read the same process at once. Only one session owns the debugger (breakpoints, stepping, writes).
It never locks the original PDB, so you can keep building while attached.
Requirements
Tool | Default location | If missing |
cdb |
|
|
msdia140.dll |
| Install the VS "Desktop development with C++" workload |
uv | PATH |
|
This repository does not include cdb.exe or msdia140.dll. Both are Microsoft software: install them yourself and use them under their own licenses (WinDbg terms of use, Visual Studio license). livedbg-mcp only calls the installed tools. cdb may not be redistributed, so it is not shipped in this repository or the plugin.
If a tool is not in its default location, point to it with an environment variable. Environment variables take precedence.
Environment variable | Meaning |
| Path to cdb.exe |
| Path to msdia140.dll |
| Location of the PDB shadow cache and lock files (default |
| PDB folders that are never rebuilt ( |
|
|
The status tool reports the paths it found and which tools are missing.
The target must be built with /DEBUG:FULL. A /DEBUG:FASTLINK PDB leaves type information in the .obj files, so a copy of the PDB alone cannot be read.
Related MCP server: gdbmcp
Installation (Claude Code plugin)
claude plugin marketplace add <path to this repository or owner/repo>claude plugin install livedbg-mcp@livedbg-marketplaceThe plugin starts the server with uv run --directory ${CLAUDE_PLUGIN_ROOT} livedbg-mcp. On first run uv installs the dependencies.
To use it without the plugin, put the same command in your MCP configuration.
Tools
Category | Tools |
Session |
|
Symbols (DIA) |
|
Read |
|
Execution control |
|
Write |
|
Unreal |
|
Qualify symbols as module!name (target!g_State, UnrealEditor-ChronoSpace!...).
Unqualified names are only looked up in modules whose symbols are already loaded.
debugger_command and evaluate pass cdb commands and expressions through as-is, but refuse the following. The dedicated tools handle these with the proper safety steps.
Refused | Use instead |
Execution commands ( |
|
Session lifetime commands ( |
|
Memory and register writes ( |
|
Constructs that run other commands indirectly ( | — |
This check guards against accidentally breaking state; it is not a security boundary. It can be bypassed on purpose.
Architecture
Each session (MCP client) runs its own server process. There is no daemon.
MCP session A ── livedbg-mcp ─┬─ reader cdb -pvr (noninvasive, never stops the target, any number)
├─ controller cdb -pd (debugger, one per process — enforced by the OS)
└─ DIA (dedicated thread)
MCP session B ── livedbg-mcp ─── reader cdb -pvr (can read while A owns the debugger)Reads: when the target is stopped, the controller reads a consistent snapshot; while it runs, the reader reads live values. A struct read while running may have fields from different moments (shown in the response's
read).Debugger ownership: ownership is a byte-range lock on
%LOCALAPPDATA%\livedbg-mcp\locks\<pid>.json. Another session's debug attach is refused, and the owner info written in the file (server pid, start time) tells who holds it. The lock is tied to a handle, so the OS releases it however the owning server dies; a dead owner never leaves a stale lock.PDBs: it reads the RSDS record (GUID/Age) from the loaded module in memory, briefly copies the build output's PDB with all share flags, verifies GUID/Age with DIA, and stores it as
<cache>\<name>.pdb\<GUID><Age>\<name>.pdb. cdb opens only this copy, throughsrv*<cache>and-sicv(ignore the original path embedded in the PE). Why memory and not the DLL on disk: if you rebuild while it runs, the file on disk is already the new build. A PDB judged mismatched is remembered and not copied again. If it is rebuilt and the file changes (size, modification time), it is checked again.Lookup speed: symbol and type lookups go through DIA, memory reads go directly through
ReadProcessMemory. cdb is used only for expression evaluation and execution control. Measured in an Unreal editor (1,138 modules):Lookup
DIA
cdb
Type layout (
AActor)1.7 ms
8.0 ms (
dt)Wildcard function search (
*Tick*)1.6 ms
83 ms (
x)A tool response (including the module lookup) takes around 15 ms.
Safety rules and their basis
Based on direct measurements against a test target on 2026-09-30.
Measurement | Result | Therefore |
Opening a PDB for writing (as the linker does) while dbghelp or DIA has it open | Sharing violation for both | Never open the original, only a copy |
Killing cdb while running, without | Target terminates | The controller always uses |
| Target survives | — |
| Target frozen permanently (RIP = bp+1, unrecoverable) | Detach must always go (stop if running) → |
|
| Same as above |
| Read succeeds, no effect on the target | Multiple read sessions coexist |
| Target keeps running | Normal shutdown path |
MCP clients close the server's stdin and force-kill the process tree 2 seconds later (Python SDK behavior). On stdin EOF, signals, or console close events, the server immediately detaches all targets in parallel. This shutdown path has little time, so:
Even if another operation (PDB copy, Unreal initialization, a long command) holds the target, it waits only 0.2 seconds and proceeds.
If the target is running, it waits 1.5 seconds for the break-in.
bc *andqdare sent without waiting for a reply; cdb processes input in order, so they run as soon as the command in progress finishes.It also closes a controller that is still being set up (loading symbols) and not yet registered.
In tests, disconnecting while stopped finished in 0.11 seconds, and disconnecting during attach setup in 1.03 seconds.
A normal detach has no time limit, so if cdb is still processing a timed-out command, it waits for that to finish before shutting down
(killing cdb while stopped guarantees a freeze). After a command times out, the next command first .echoes a marker to resynchronize with cdb.
Without that, a late prompt would be mistaken for a stop, and the target would appear "stopped" while actually running.
Remaining risks
If the server is killed without a chance to clean up (Task Manager, etc.), a stopped target freezes, and a target with breakpoints inserted crashes at the next hit.
If, at the moment of shutdown, cdb is processing a command that takes more than 2 seconds (loading a large PDB, etc.) or attach is waiting for its first prompt, cleanup may not finish before the client's forced kill.
Detach when you are done debugging.
Memory writes
Only allowed while owning the debugger and stopped, and only through
write_memory(read sessions can also write memory, so writes throughdebugger_commandorevaluateare refused).Type and size are checked against the PDB, every page in the written range is checked to be writable and non-executable, and the value is read back to verify.
Value formats: integers (decimal or
0x), floats,true/false,hex:0a0b...(exactly that many bytes). Structs (even of size 1, 2, 4 or 8, e.g.TObjectPtr) do not accept integers, onlyhex:.A bitfield write changes only its own bits and leaves neighboring bits in the same storage unit untouched. dx returns a bitfield's address as the address of its containing byte, indistinguishable from a normal field, so bitfields are detected with the C++ expression evaluator (
??) and the bit position is read from the parent's raw layout.Every write is recorded and can be reverted with
undo_write. If the value changed in the meantime, it is not overwritten.A target stopped at an arbitrary point may be in the middle of another thread updating that object, and optimized code may hold the value in a register. When possible, set a breakpoint where the object is quiet (start of a frame, etc.) and write there.
Unreal
Built and verified on the UE 5.8 editor (Development, Win64). Other engine versions and game builds are untested. Struct offsets are read from the PDB, and unknown structures raise errors instead of guessing, but correct behavior is not guaranteed. Run
tests\test_unreal_live.pybefore using it with another version.
natvis only partly works in cdb
Unreal.natvis (FString, TArray, FName ...) is not embedded in the PDB (only per-module natvis files are).
The server automatically .nvloads Engine\Extras\VisualStudioDebugging\Unreal.natvis from the engine installation.
That file is written for the Visual Studio debugger, and cdb's dx has its own natvis implementation,
so some parts break (confirmed on 5.8).
Cause | Broken types |
dx interprets the reference cast | FName → UObject names, soft paths, gameplay tags |
Format specifiers dx does not know ( | FGuid, hash and ID types |
TSet display rule fails (cause not determined) | TSet, TMap |
TArray, FString and math types display correctly with dx. The VS debugger engine (vsdbg) may not be used by other tools under its license.
Unreal decoders (ue_*)
Frequently used types are decoded directly from memory instead of through natvis. All struct offsets come from the PDB (DIA), and each decoder validates what it reads, so a changed structure produces an error rather than a silently wrong value.
Type | Validation |
FName | ComparisonId of the name pool entry matches, block range. Builds without ComparisonId reject control characters and invalid UTF-16 |
Enums | Size and signedness from the underlying type in the PDB (200 in |
UObject references (TObjectPtr, TSubclassOf, pointers) → name, class, full path | Global object array[InternalIndex] == this address |
TWeakObjectPtr | SerialNumber of the object array item matches (stale otherwise) |
TArray / TSet / TMap | Number of allocated bits == ArrayNum − NumFreeIndices |
TCompactSet (the new TSet implementation in 5.8, | 0 ≤ NumElements ≤ MaxElements |
TSoftObjectPtr / TSoftClassPtr, FString | Go through the FName and array validation |
Dynamic delegates | Binding = (weak object, function FName) |
Sparse delegates ( | Looked up in the global |
Native delegates | Kind determined from the binding instance's vtable symbol → target object and function symbol. Bindings in modules without a PDB (engine) show as |
The entry points are debug symbols UE plants in every module (
GNameBlocksDebug,GObjectArrayForDebugVisualizers), so it works with only the game module's PDB, no engine PDBs. The base module is chosen automatically: game module → plugins → engine. If the game module's PDB cannot be used (built differently from the running DLL, etc.), another module is used and the reason is shown in theue_*results andstatus. Common engine types (FName, objects, containers) are still visible, but game class fields are not. This happens when a committed DLL is pulled and not relinked. Rebuild the game module, or get the PDB together with the DLL.type_modulein theue_worlds/ue_find_objectsresults is the module qualifier to use when casting in expressions. Example:ue_inspect(pid, "*(UnrealEditor_ChronoSpace!ACSCharacterPlayer*)0x1e1d3c6e600", depth=1)Structs are expanded through their PDB fields down to
depth; base classes are shown by name only (the UObject hierarchy has hundreds of fields).For engine-internal TMaps whose instance layout is not in the PDB, such as the sparse delegate storage, element positions are computed from another TMap instance's container layout plus key/value sizes and alignment (the allocated-bit validation catches computation mistakes).
Not supported: FText. Blueprint variables (reflection) are the next step.
Other notes
UE modules are
/GR-(RTTI off) by default regardless of build configuration (CppCompileEnvironment.bUseRTTI = false).dynamic_typedetermines the actual class from the vftable symbol (??_7Class@@6B@), so RTTI is not needed.For a launcher engine, the "Editor symbols for debugging" option must be enabled to install engine PDBs. If installed, add
Engine\Binaries\Win64toLIVEDBG_SYMBOL_DIRSto use them in place without copying (safe, since they are never rebuilt).Blueprint variables are not in the PDB (they only exist in reflection). Not supported yet.
On a listen server, stopping one side for long makes the other side drop on a network timeout.
The Development editor is an optimized build, so local variables may be missing from
locals.cdb handles pipe I/O in the system ANSI code page (CP949 on Korean Windows), so the server uses that encoding too. Korean text in
FString(UTF-16) shows correctly inevaluate. UTF-8char*strings in memory and line display of UTF-8 source files (lsa) come out already garbled from cdb.ue_inspectdecodes directly without going through cdb, so it is unaffected.
Development
The tests run in five steps, in order from the top.
Step | Test | Needs | Checks |
1 |
| VS C++ workload | Builds the integration test target ( |
2 |
| Nothing (no cdb or target) | Command blocking, address parsing, value and bitfield encoding, owner lock, PDB cache races, late break-in detection |
3 |
| Target from step 1, cdb, msdia | Starts the server through a real MCP client (stdio) and attaches to the target. Scenarios below |
4 |
| Nothing | Container decoding on synthetic memory (TCompactSet is checked here because a live instance is hard to catch) |
5 |
| A running Unreal editor | Attaches read-only to the editor and cross-checks decoder results against values dx displays correctly (TArray counts, etc.). Does not stop the editor. Run after upgrading the engine |
powershell -NoProfile -ExecutionPolicy Bypass -File tests\fixtures\build.ps1uv run python tests\test_units.pyuv run python tests\test_mcp_e2e.pyuv run python tests\test_unreal_decoders.pyuv run python tests\test_unreal_live.pyThe build script runs with -ExecutionPolicy Bypass for machines where the execution policy blocks it (applies to that process only).
test_unreal_live.py finds UnrealEditor.exe if the pid is omitted.
e2e scenarios (G takes about 35 seconds, so the whole run takes a few minutes):
Scenario | Checks |
A | Core flow: debug attach, live reads, type layout, dynamic type without RTTI, breakpoints, writes while stopped. A second session's debug attach is refused, read allowed, writes refused. The target survives and keeps running when the client disconnects while it is stopped |
B | All remaining tools: conditional and source-line breakpoints, step, locals, break_in, symbol_at, read_memory, write and undo, bitfield writes, refusing code and struct writes, command blocking |
C | A real linker rebuild that overwrites the same PDB succeeds while attached, and a new session detects the PDB mismatch |
D | If debug attach fails during setup, the target is not left stopped, the lock is released, and attaching works again |
E | After a command times out, the running/stopped state still matches reality |
F | If the server shuts down during debug attach setup, the not-yet-registered controller is closed and the target survives |
G | Detaching while cdb is still processing a timed-out command does not kill it with the target stopped |
When done, check that no cdb processes are left behind.
License
MIT (LICENSE). The dependencies mcp and comtypes are MIT as well.
cdb.exe and msdia140.dll are not included in this repository and are not covered by this license (see Requirements).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Control Unreal Engine to browse assets, import content, and manage levels and sequences. Automate…
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
Drive a live Cinevva game session: edit game files, import CC0 assets, preview changes.
Live browser debugging for AI assistants — DOM, console, network via MCP.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides GDB and clangd-based tools for debugging C++ programs, enabling step execution, variable inspection, diagnostics, and combined runtime-static analysis.271MIT
- AlicenseNot gradedqualityDmaintenanceAttaches to a running C++ process and exposes tools to inspect live memory via a resident GDB subprocess, enabling LLMs to read fields, follow pointers, and access STL containers without modifying target code.MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI clients to inspect live memory of a running C++ process on Windows using cdb.exe, providing tools to evaluate expressions, retrieve map entries, and enumerate containers without modifying target code.-
- AlicenseNot gradedqualityCmaintenanceReverse engineering against a running Windows process instead of the file on disk: memory reads, pattern and value scanning, disassembly of the code that actually executed, resolved IAT thunks, caller-chain tracing, and structure recovery. Complements the Ghidra and IDA servers rather than replacing them — correlate_addr maps a runtime address back to a module and RVA.MIT