io.github.kengraryPublished by GitHub account kengraryv0.2.1Updated Oct 29, 2026
Analyze Java heap dumps locally with Eclipse MAT, including live JVM capture.
Local stdio MCP server that lets an assistant analyze Java heap dumps with Eclipse MAT, including capturing live dumps from running JVMs.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
[JVMind MAT Heap Dump Analyzer MCP server]
English | 中文
Java heap dump analysis built on the Eclipse Memory Analyzer (MAT) engine: upload → parse → MAT-like web queries → domain diagnostics (connection-pool leaks and more) → natural-language agent diagnosis.
Status: the Java parser and query service are tested. MCP Server
v0.2.1is published on PyPI and the official MCP Registry. Python platform integration is still in progress. See PROJECT-STATUS.md.
mat-study/README.md
(the design blueprint; Chinese).uvx jvmind-mat-mcp, local stdio).A local stdio MCP server that exposes MAT heap analysis to Claude Desktop,
Cursor, and VS Code. It can discover local Java processes and capture a live
heap dump from a running JVM, or open an existing .hprof file. Heap dumps
never leave the machine; the MAT helper binds to 127.0.0.1 only.
Capabilities: list_java_processes / dump_java_heap for live capture,
open_heapdump for existing files, then mat_overview / mat_histogram /
mat_dominator / mat_threads / mat_object / mat_path2gc / mat_oql /
mat_leak_suspects / mat_diagnose_oom and more — 19 tools in total.
Requirements: Python 3.10+, JDK 21+, Eclipse MAT 1.17.x (a small query bundle is installed into MAT on first use).
All analysis tools take the report_id returned by open_heapdump.
open_heapdump — open a local .hprof, start background indexing, return a report_idget_heapdump_status — poll parse status, progress, and phaselist_heapdumps — list heap dumps known to this MCP serverclose_heapdump — release a heap dump handle and optionally stop the MAT helperlist_java_processes — discover local attachable JVMs (pid, main class, command; MAT helper excluded)dump_java_heap — preview and capture a live heap dump, then start MAT parsing (confirm=true)mat_overview — heap overview: used/committed/live heap, object/class/classloader counts, JDK versionmat_histogram — class histogram sorted by shallow, retained, or object countmat_dominator — dominator tree of the largest retained objects, with parent drill-downmat_threads — list threads or drill into stack frames and frame localsmat_threadlocals — inspect ThreadLocal values grouped by value class or threadmat_object — inspect a single object's fields, statics, references, and GC rootmat_path2gc — shortest path from an object to a GC rootmat_oql — run an OQL query and return rows plus a reusable result set idmat_leak_suspects — run LeakHunter and return suspects with retained sizes and descriptionsmat_diagnose_oom — composite OOM diagnosis: leak suspects + SQL in threads + dominator analysismat_connection_pools — diagnose database connection pools and leaked connectionsmat_top_consumers — top memory consumers by retained heapmat_sql_in_threads — find SQL statements in thread stacksmat-study/ — design documents (Chinese)parser-cli/ — parsing layer (hprof → index)query-service/ — query layer (OSGi bundle, :8090) ✅mcp-server/ — local stdio MCP (✅ v0.2.1 published)marketplace/ — directory submission pack (🟡 prepared, not submitted)eclipse-plugin) with a
p2 repository or a local Directory target; do not add <dependencies>.plugins/, add a line to bundles.info
(auto-start=true), and restart with -clean (not dropins/).dumpDir (= the dump directory).jvmind-mat-mcp; Registry name io.github.kengrary/jvmind-mat.
After changing the Java query layer, rerun
mcp-server/scripts/vendor-bundle.sh, otherwise the wheel ships a stale bundle.com.jvmind.mat.query into MAT's
plugins/ and bundles.info; the MAT install must be writable.jmap -dump:live: it dumps only live objects, triggers a
Full GC, and may pause the target JVM. The default output is the server's
current working directory; override it with JVMIND_MCP_DUMP_DIR or the
tool's output_dir.uv / stdioSource: README.md at commit 3359777
Open a local Java heap dump (.hprof) by absolute path. Starts MAT indexing in the background and returns a report_id immediately with status=PARSING. Poll get_heapdump_status until DONE. / 按绝对路径打开本地 Java 堆转储（.hprof）。后台启动 MAT 解析并立即返回 report_id 与 status=PARSING，用 get_heapdump_status 轮询直到 DONE。
pathrequiredGet parse status and progress for a heap dump report. / 查询堆转储报告的解析状态与进度。
report_idrequiredList heap dumps known to this MCP server with their status. / 列出本 MCP 服务已知的堆转储及其状态。
Takes no parameters.
Release a heap dump handle. Set stop_service=true to also stop the MAT helper process. / 释放堆转储句柄；stop_service=true 时同时停止 MAT 辅助进程。
report_idrequiredstop_serviceDiscover local Java processes that can be attached for a live heap dump. Returns pid, main class, command, and masked JVM arguments. The managed MAT helper is excluded. / 主动发现本机可 attach 的 Java 进程，返回 pid、主类、命令行和已掩码的 JVM 参数；MAT 辅助进程会被排除。
Takes no parameters.
Capture a LIVE heap dump from a running JVM and start MAT parsing. First call with confirm=false (default) to preview the target, output directory, disk space, and timeout; call again with confirm=true to execute. A live dump triggers a Full GC and may pause the target JVM. The dump is written to output_dir (default: current working directory) and is automatically opened for MAT parsing. / 从运行中的 JVM 抓取 live 堆转储并自动开始 MAT 解析。先用默认 confirm=false 预览目标、输出目录、磁盘空间和超时，再用 confirm=true 执行。live dump 会触发 一次 Full GC，可能暂停目标 JVM；默认输出到当前目录。
pidrequiredconfirmtimeoutoutput_dirShow heap overview (used/committed/live heap, object/class/classloader counts, JDK version, leak suspect count). Always call this first to understand a heapdump. / 展示堆总览（已用/已提交/存活堆、对象/类/类加载器数量、JDK 版本、泄漏嫌疑数量）。分析 heapdump 时先调用本工具。
report_idrequiredClass histogram sorted by shallow/retained/count. Top-N by default; pass top to override. objectSet reuses a prior OQL/RS result. / 按 shallow/retained/count 排序的类直方图，默认 Top-20。objectSet 可复用先前 OQL/RS 结果。
topsortobjectSetreport_idrequiredDominator tree: list biggest retained-heap dominators, drill down by passing parent objectId. / 支配树：列出 retained 最大的支配者，传 parent=objectId 可下钻。
topparentreport_idrequiredList threads (name/state/daemon/frameCount), or drill into a thread's stack frames (pass thread=id) or frame locals (pass frame=idx). / 列出线程（名/状态/daemon/帧数），或下钻到某线程的栈帧（传 thread=id）、某帧的局部变量（再传 frame=idx）。
framethreadreport_idrequiredInspect thread locals grouped by valueClass (default) or thread. Useful for finding thread-local leaks. / 按 valueClass（默认）或 thread 分组查看 ThreadLocal，常用于发现 ThreadLocal 泄漏。
groupByreport_idrequiredInspect a single object (class, fields, statics, in/out refs, GC root). Required: object id. / 检查单个对象（类、字段、静态字段、入/出引用、GC Root）。必须传 object id。
idrequiredreport_idrequiredPath to GC roots
Read-only, synchronous lookup of the shortest reference chains from one object to GC roots, explaining why that object is still reachable and not collected. Returns up to five linear paths plus MAT's path tree. Typical flow: get an object id from mat_object, mat_histogram, mat_dominator, or a mat_leak_suspects preferredObjectId, confirm it with mat_object, then call this tool. Use mat_dominator instead when you want to know which object retains an entire subtree; use mat_leak_suspects when you do not yet have a specific object. Requires the report_id of a parsed dump (status=DONE).
objectrequiredreport_idrequiredexcludeWeakSoftRun an OQL query against the heap (slow!). Returns rows + a reusable resultSetId. Examples: "SELECT * FROM com.example.Foo s", "SELECT s.id.toString() FROM java.lang.String s". OQL can read arbitrary strings from the heap; handle results as private data. / 执行 OQL 查询（较慢）。返回行和可复用的 resultSetId。示例：SELECT * FROM com.example.Foo s。OQL 可读取堆内任意字符串，注意隐私。
qrequiredsortviewlimitreport_idrequiredRun LeakHunter (async) — returns leak suspects with retained size and description. SLOW: may take a minute. / 运行 LeakHunter（异步），返回疑似泄漏点及 retained 大小与描述。慢查询，可能耗时数十秒。
report_idrequiredRun comprehensive OOM diagnosis (async) combining leak suspects + SQL-in-threads + dominator analysis. / 综合 OOM 诊断（异步），聚合泄漏嫌疑、线程中的 SQL、支配树分析。
onlyRiskyreport_idrequiredculpritPctDiagnose DB connection pools (active/idle counts + leaked connections held > thresholdMs). / 诊断数据库连接池（活跃/空闲数 + 持有超过 thresholdMs 的泄漏连接）。
report_idrequiredthresholdMsTop memory consumers
Read-only Top Consumers report: biggest individual objects plus retained-size breakdowns by class, class loader, and package. Use this as a quick 'who is using the most memory' overview after mat_overview. Prefer mat_histogram when you need a sortable list of every class with instance counts and shallow/retained sizes, and mat_dominator when you need to walk the object graph downward from a specific parent object. Requires the report_id of a parsed dump (status=DONE).
report_idrequiredSQL in thread stacks
Read-only scan of thread stacks for JDBC PreparedStatement objects and SQL strings, used to spot long-running or heavy queries held by threads at OOM time. Requires the report_id of a parsed dump (status=DONE). Results are sorted risky-first, then by the owning thread's retained heap, and include threadId, threadName, threadRetainedBytes, frame, source, objectId, sql, risk (risky|harmless|unknown), and reason. With onlyRisky=true, heartbeat/validation statements such as SELECT 1, SELECT 'x', /* ping */ and VALUES(1) are filtered out; pass onlyRisky=false to see all SQL-like strings.
onlyRiskyreport_idrequired90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
uvx jvmind-mat-mcp doctor # checks JDK 21 / MAT 1.17 / permissions User uploads a heap dump │ [Python/FastAPI] ← in progress (TODO-PYTHON-TEAM.md) upload / queue / progress / auth / agent ├── fork ─────────────▶ [parser-cli / V1] hprof → *.index ✅ tested │ (writes to NFS) └── reverse proxy ────▶ [query-service] queries over indexes ✅ tested (OSGi bundle, :8090) histogram / dominators / threads / OQL + Leak Suspects / path2gc etc. Shared: NFS (dump files) + PostgreSQL (tasks/reports)
Local MCP path (v0.2.1 published): Claude Desktop / Cursor / VS Code │ stdio ▼ [mcp-server] ──HTTP 127.0.0.1──▶ [query-service :8090] └── runs MAT ParseHeapDump when index files are missing (reuses the parser-cli V1 logic)