Skip to main content
Glama
livedbg-mcp

livedbg-mcp

by Lagooneng

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.natvis automatically.

  • 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

%LOCALAPPDATA%\Microsoft\WindowsApps\cdbX64.exe

winget install Microsoft.WinDbg

msdia140.dll

DIA SDK\bin\amd64\msdia140.dll of the VS instance found by vswhere

Install the VS "Desktop development with C++" workload

uv

PATH

winget install astral-sh.uv

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

LIVEDBG_CDB_PATH

Path to cdb.exe

LIVEDBG_MSDIA_PATH

Path to msdia140.dll

LIVEDBG_CACHE_DIR

Location of the PDB shadow cache and lock files (default %LOCALAPPDATA%\livedbg-mcp)

LIVEDBG_SYMBOL_DIRS

PDB folders that are never rebuilt (;-separated). Opened in place without copying. Example: Engine\Binaries\Win64 of an installed (non-source) engine

LIVEDBG_MS_SYMBOLS

1 downloads and caches OS symbols from the Microsoft symbol server (off by default; uses the network)

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-marketplace

The 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

status list_processes attach detach modules prepare_symbols

Symbols (DIA)

find_symbols type_layout symbol_at dynamic_type

Read

evaluate (cdb dx + natvis) read_memory debugger_command (for inspection, see below)

Execution control

set_breakpoint list_breakpoints clear_breakpoint wait break_in resume step stack locals

Write

write_memory undo_write write_history

Unreal

ue_inspect ue_find_objects ue_worlds

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 (g, p, t families, including thread-prefixed forms like ~0 g)

resume step

Session lifetime commands (q qd .kill .detach ...), freezing or suspending threads

detach

Memory and register writes (eb ed f m, dx x = 1, ++ --, breakpoint conditions containing an assignment)

write_memory

Constructs that run other commands indirectly (.if blocks, scripts, aliases, !for_each_*, dx ExecuteCommand)

—

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, through srv*<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 -pd

Target terminates

The controller always uses -pd

-pd, running, no breakpoints, kill cdb

Target survives

—

-pd, kill cdb while stopped at a breakpoint

Target frozen permanently (RIP = bp+1, unrecoverable)

Detach must always go (stop if running) → bc * → qd

-pd, kill cdb while running with breakpoints inserted

0xCC left behind → crash when hit

Same as above

cdb -pvr while an invasive cdb is attached

Read succeeds, no effect on the target

Multiple read sessions coexist

bc * → qd while stopped

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 * and qd are 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 through debugger_command or evaluate are 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, only hex:.

  • 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.py before 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 (T&)x differently

FName → UObject names, soft paths, gameplay tags

Format specifiers dx does not know (X Xb xb na ...)

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 enum class E : uint8 is 200). Error instead of guessing if the definition is missing

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, UE_USE_COMPACT_SET_AS_DEFAULT)

0 ≤ NumElements ≤ MaxElements

TSoftObjectPtr / TSoftClassPtr, FString

Go through the FName and array validation

Dynamic delegates

Binding = (weak object, function FName)

Sparse delegates (OnComponentBeginOverlap, etc.)

Looked up in the global FSparseDelegateStorage. Given only the field, the owner object is derived from the registered offset map and validated as a UObject

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 unknown

  • 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 the ue_* results and status. 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_module in the ue_worlds / ue_find_objects results 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_type determines 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\Win64 to LIVEDBG_SYMBOL_DIRS to 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 in evaluate. UTF-8 char* strings in memory and line display of UTF-8 source files (lsa) come out already garbled from cdb. ue_inspect decodes 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

tests\fixtures\build.ps1

VS C++ workload

Builds the integration test target (/GR-, no RTTI) into tests\fixtures\bin

2

tests\test_units.py

Nothing (no cdb or target)

Command blocking, address parsing, value and bitfield encoding, owner lock, PDB cache races, late break-in detection

3

tests\test_mcp_e2e.py

Target from step 1, cdb, msdia

Starts the server through a real MCP client (stdio) and attaches to the target. Scenarios below

4

tests\test_unreal_decoders.py

Nothing

Container decoding on synthetic memory (TCompactSet is checked here because a live instance is hard to catch)

5

tests\test_unreal_live.py [pid]

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.ps1
uv run python tests\test_units.py
uv run python tests\test_mcp_e2e.py
uv run python tests\test_unreal_decoders.py
uv run python tests\test_unreal_live.py

The 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides GDB and clangd-based tools for debugging C++ programs, enabling step execution, variable inspection, diagnostics, and combined runtime-static analysis.
      27
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Attaches 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
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Reverse 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