A local stdio MCP server that brings Eclipse Memory Analyzer (MAT) heap-dump analysis into Claude Desktop, Cursor, and VS Code, so an AI agent can open or capture a Java heap dump and run MAT-style diagnostics — all dumps stay on the machine.
Open & manage dumps — open_heapdump (by absolute .hprof path), get_heapdump_status (poll parse progress), list_heapdumps, close_heapdump (optionally stop the MAT helper).
Live capture — list_java_processes to discover attachable JVMs, dump_java_heap to preview then capture a live heap dump (jmap -dump:live, warn: triggers Full GC) and auto-start parsing.
Heap overview — mat_overview for used/committed/live heap, object/class/classloader counts, JDK version, and leak-suspect count.
Structure exploration — mat_histogram (sort by shallow/retained/count), mat_dominator (dominator tree with parent drill-down), mat_top_consumers (biggest retained objects/classes).
Object-level inspection — mat_object (fields, statics, in/out refs, GC root), mat_path2gc (shortest path to a GC root, excluding weak/soft by default).
Thread analysis — mat_threads (threads → stack frames → frame locals), mat_threadlocals (grouped by value class or thread, for ThreadLocal leaks), mat_sql_in_threads (SQL in thread stacks).
Leak & OOM diagnostics — mat_leak_suspects (LeakHunter), mat_diagnose_oom (composite: suspects + SQL in threads + dominators), mat_connection_pools (active/idle counts and connections held past a threshold).
Ad-hoc queries — mat_oql to run OQL, returning rows plus a reusable result set id (slow, and can read arbitrary heap strings, so treat output as private).
Privacy/safety — heap dumps never leave the machine, MAT helper binds to 127.0.0.1 only; tools take a report_id, and live capture requires explicit confirm=true.
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.
Project overview → this file + mat-study/README.md
(the design blueprint; Chinese).
Current progress → PROJECT-STATUS.md (completed work, remaining tasks, lessons learned).
Python team onboarding → TODO-PYTHON-TEAM.md (task list, API contract, acceptance criteria).
Run the query service → query-service/DEPLOY.md (deploy + curl verification).
Run the parser → parser-cli/v1-parsehd/README.md (no build required; uses the MAT distribution).
Analyze heap dumps from Claude/Cursor/VS Code →
mcp-server/README.md (uvx jvmind-mat-mcp, local stdio).
Related MCP server: javaperf
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.
uvx jvmind-mat-mcp doctor # checks JDK 21 / MAT 1.17 / permissionsChannel | Location |
PyPI | |
Official MCP Registry |
|
MCPRush | https://mcprush.com/kengrary/jvmind-mat-heap-dump-analyzer-mcp |
Documentation |
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_id
get_heapdump_status — poll parse status, progress, and phase
list_heapdumps — list heap dumps known to this MCP server
close_heapdump — release a heap dump handle and optionally stop the MAT helper
list_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 version
mat_histogram — class histogram sorted by shallow, retained, or object count
mat_dominator — dominator tree of the largest retained objects, with parent drill-down
mat_threads — list threads or drill into stack frames and frame locals
mat_threadlocals — inspect ThreadLocal values grouped by value class or thread
mat_object — inspect a single object's fields, statics, references, and GC root
mat_path2gc — shortest path from an object to a GC root
mat_oql — run an OQL query and return rows plus a reusable result set id
mat_leak_suspects — run LeakHunter and return suspects with retained sizes and descriptions
mat_diagnose_oom — composite OOM diagnosis: leak suspects + SQL in threads + dominator analysis
mat_connection_pools — diagnose database connection pools and leaked connections
mat_top_consumers — top memory consumers by retained heap
mat_sql_in_threads — find SQL statements in thread stacks
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)File | Contents |
English overview (this file) | |
Chinese overview | |
Milestones, module status, TODOs, lessons learned | |
Python integration task list, API contract, acceptance |
mat-study/ — design documents (Chinese)# | Document | What it covers |
— | Design blueprint (four-layer architecture, decisions, milestones) | |
01 | How MAT works and how to reuse it; index file format | |
02 | Dominator tree, paths, retained size; web backend design | |
03 | What else a heap dump can answer; pools, thread pools, classloaders | |
04 | How an LLM drives MAT; tool granularity and output trimming | |
05 | Upload, queue, progress, three-layer soft-reference cache | |
06 | Finalized choices and the four-view API contract | |
07 | How to connect to the existing platform (required for the Python team) | |
08 | 57 queries reviewed; gap priorities | |
09 | Making the web UI feel like MAT | |
10 | Inspector features and what is already implemented | |
12 | Phased plan for the Python side | |
13 | Finding the OOM-triggering thread and its SQL | |
14 | Endpoint mapping, async state machine, integration rules |
parser-cli/ — parsing layer (hprof → index)File | Contents |
Parser overview (V1/V2 routes) | |
How to obtain MAT dependencies, version/JDK matrix, bundle list | |
V1 (zero build; MAT distribution + text progress) — current | |
V1 verification report (real hprof, three bugs fixed) | |
| Progress parser (Python; reusable by the worker) |
| Worker snippet for calling the parser |
| V2 skeleton (self-built jar + JSONL progress; not active) |
query-service/ — query layer (OSGi bundle, :8090) ✅File | Contents |
Service overview (endpoints, SnapshotManager, route 2) | |
Deploy + end-to-end verification (bundles.info + | |
Embedded Equinox test and CNF fix (why route 2) | |
Build troubleshooting (p2 repositories, JDK versions) | |
| Service implementation: core/http/model/task/view/equinox |
mcp-server/ — local stdio MCP (✅ v0.2.1 published)File | Contents |
Install, client config, 19 tools, privacy, troubleshooting | |
| MCP SDK tool registration |
| Heap dump registry, background parsing, MAT lifecycle |
| Query-service OSGi bundle shipped with the package |
Glama review image (MAT/JDK not included; mount at runtime) | |
| Unit tests, stdio protocol tests, optional real-MAT integration tests |
marketplace/ — directory submission pack (🟡 prepared, not submitted)File | Contents |
Platform status, remaining steps, quality gaps | |
Shared name, description, tags, install command | |
| MCPB manifest (Smithery skipped, kept for later) |
Form copy and steps per platform |
Module | Form | Status | Entry point |
parser-cli | V1 = MAT command; V2 = standalone jar | ✅ V1 tested |
|
query-service | OSGi bundle (HTTP :8090) | ✅ tested |
|
mcp-server | Python stdio MCP (PyPI + official Registry) | ✅ v0.2.1 published |
|
marketplace | Directory copy (Smithery skipped) | 🟡 prepared, pending submission |
|
Python integration | FastAPI + DB + agent | ⏳ in progress |
|
MAT dependencies are not on Maven Central → use Tycho (eclipse-plugin) with a
p2 repository or a local Directory target; do not add <dependencies>.
Version ↔ JDK: 1.17 → JDK 21, 1.14 → JDK 17, 1.12 → JDK 11 (keep all three places in sync).
Deployment: copy the jar into plugins/, add a line to bundles.info
(auto-start=true), and restart with -clean (not dropins/).
The query service has no authentication and is intranet-only. The Python proxy
injects dumpDir (= the dump directory).
Reopening a dump requires both the hprof and index files on a seekable filesystem (NFS works).
MCP package 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.
On first use the MCP server writes com.jvmind.mat.query into MAT's
plugins/ and bundles.info; the MAT install must be writable.
Live capture uses 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.
Smithery is skipped for now: its web UI only exposes remote HTTPS URLs and the CLI server-creation endpoint was removed. MCPB artifacts are kept for a later retry. The Docker image is for directory review; real analysis still needs MAT + JDK 21 on the host.
Parsing/query: Java 21 + Eclipse MAT 1.17 (OSGi/Equinox)
MCP server: Python 3.10+ / MCP Python SDK 2.x / uv / stdio
Platform/agent: Python + FastAPI (the existing JVMind platform)
Storage: NFS (dump files) + PostgreSQL (tasks/reports)
Distribution: PyPI + official MCP Registry; mcp.so, Glama, and PulseMCP materials are prepared; Smithery is skipped
License: MIT for this project (see LICENSE); Eclipse MAT is EPL-2.0 and is not redistributed
Release a heap dump handle. Set stop_service=true to also stop the MAT helper process. / 释放堆转储句柄；stop_service=true 时同时停止 MAT 辅助进程。
Inputs: report_id (required), stop_service. Returns: result
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；默认输出到当前目录。
Inputs: pid (required), confirm, timeout, output_dir. Returns: result
Get parse status and progress for a heap dump report. / 查询堆转储报告的解析状态与进度。
Inputs: report_id (required). Returns: result
List heap dumps known to this MCP server with their status. / 列出本 MCP 服务已知的堆转储及其状态。
Inputs: no named parameters. Returns: result
Discover 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 辅助进程会被排除。
Inputs: no named parameters. Returns: result
Diagnose DB connection pools (active/idle counts + leaked connections held > thresholdMs). / 诊断数据库连接池（活跃/空闲数 + 持有超过 thresholdMs 的泄漏连接）。
Inputs: report_id (required), thresholdMs. Returns: result
Run comprehensive OOM diagnosis (async) combining leak suspects + SQL-in-threads + dominator analysis. / 综合 OOM 诊断（异步），聚合泄漏嫌疑、线程中的 SQL、支配树分析。
Inputs: report_id (required), onlyRisky, culpritPct. Returns: result
Dominator tree: list biggest retained-heap dominators, drill down by passing parent objectId. / 支配树：列出 retained 最大的支配者，传 parent=objectId 可下钻。
Inputs: report_id (required), top, parent. Returns: result
Class 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 结果。
Inputs: report_id (required), top, sort, objectSet. Returns: result
Run LeakHunter (async) — returns leak suspects with retained size and description. SLOW: may take a minute. / 运行 LeakHunter（异步），返回疑似泄漏点及 retained 大小与描述。慢查询，可能耗时数十秒。
Inputs: report_id (required). Returns: result
Inspect a single object (class, fields, statics, in/out refs, GC root). Required: object id. / 检查单个对象（类、字段、静态字段、入/出引用、GC Root）。必须传 object id。
Inputs: id (required), report_id (required). Returns: result
Run 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 可读取堆内任意字符串，注意隐私。
Inputs: q (required), report_id (required), sort, view, +1 more. Returns: result
Show 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 时先调用本工具。
Inputs: report_id (required). Returns: result
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).
Inputs: object (required), report_id (required), excludeWeakSoft. Returns: result
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.
Inputs: report_id (required), onlyRisky. Returns: result
Inspect thread locals grouped by valueClass (default) or thread. Useful for finding thread-local leaks. / 按 valueClass（默认）或 thread 分组查看 ThreadLocal，常用于发现 ThreadLocal 泄漏。
Inputs: report_id (required), groupBy. Returns: result
List 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）。
Inputs: report_id (required), frame, thread. Returns: result
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).
Inputs: report_id (required). Returns: result
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。
Inputs: path (required). Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 19 tools
Each tool targets a distinct analysis artifact (histogram, dominator tree, top consumers, threads, thread locals, GC paths, OQL, connection pools), and descriptions explicitly cross-reference when to prefer a sibling tool (e.g. mat_histogram vs mat_top_consumers vs mat_dominator, mat_path2gc vs mat_dominator). Composite tools like mat_diagnose_oom are clearly framed as aggregations rather than duplicates.
There is a readable two-tier convention: lifecycle tools use plain verb_noun (open_heapdump, get_heapdump_status, list_heapdumps, close_heapdump, dump_java_heap), and analysis tools are uniformly mat_-prefixed. Minor deviations like mat_threadlocals and mat_path2gc (digit abbreviation) break the pattern slightly.
Nineteen tools is on the heavy side of the ideal range, but heap-dump analysis genuinely has many distinct report types plus a lifecycle group (open/status/list/close/live dump/process discovery). Little appears redundant, though a couple of composite tools (mat_diagnose_oom) could arguably be derived from primitives.
The surface covers the full lifecycle (discover processes, capture live dumps, open, poll status, list, close) and a broad analysis set (overview, histogram, dominator, top consumers, threads, thread locals, object inspection, GC paths, leak suspects, connection pools, SQL-in-threads, OQL). No obvious dead ends for typical OOM/leak investigations.
Repository knowledge graph MCP server for codebase understanding and debugging.
MCP server to assist with JxBrowser development.
Analytics and debugging for your MCP server — explore usage and sessions, then root-cause errors.
