mcp-mat — Claude Code MCP server: Java heap dump analysis
Runs Eclipse MAT reports on a Java heap dump and returns the findings in chat. Useful when an app dies from memory pressure and you would rather not open the MAT desktop app.
claude mcp add --env MAT_HOME=<MAT_HOME> --env JAVA_PATH=<JAVA_PATH> --env MAT_XMX_MB=<MAT_XMX_MB> --transport stdio mcp-mat -- npx -y mcp-matWhat mcp-mat does
The server drives Eclipse MAT headless by calling java -jar org.eclipse.equinox.launcher_*.jar directly. Six tools come with it. mat_healthcheck confirms the launcher and Java are reachable, mat_parse_report fires predefined reports such as leak suspects or system overview, mat_oql_query runs OQL and returns rows inline, mat_run_command exposes one of 56 built-in analysis commands, mat_index_status tells you whether an index already exists for a dump, and mat_oql_spec returns guidance on OQL syntax.
The command list under mat_run_command covers histogram, dominator_tree, path2gc, thread_overview, leakhunter, collection and reference reports, top_consumers, and export_hprof. Four of them — delta_histogram, leakhunter2, find_leaks2, comparison_report — need a second .hprof file to compare against.
Eclipse MAT itself has to be installed first; point MAT_HOME at its directory. Everything else in the environment is optional: JAVA_PATH falls back to java, MAT_XMX_MB to 4096, and the timeout to 1800 seconds. If the MAT launcher is missing or broken, nothing runs, so calling mat_healthcheck first is the quick way to find out.
What it helps with
- investigate a Java heap dump after an out-of-memory crash
- hunt leaks with leak suspects and path to GC roots
- compare two dumps to see which classes grew
- read a histogram and dominator tree without launching the MAT GUI
- query live objects with OQL from the chat
Example prompts for the agent
- Check whether
heap.hprofis already indexed and build the index if not - Run a histogram on
heap.hprofand list the top classes by instance count - Show path to GC roots for
com.example.Cacheusing mcp-mat
How to install mcp-mat
Platform CLI
claude mcp add --env MAT_HOME=<MAT_HOME> --env JAVA_PATH=<JAVA_PATH> --env MAT_XMX_MB=<MAT_XMX_MB> --transport stdio mcp-mat -- npx -y mcp-matReplace <…> with your own values
Platform CLI
codex mcp add mcp-mat --env MAT_HOME=<MAT_HOME> --env JAVA_PATH=<JAVA_PATH> --env MAT_XMX_MB=<MAT_XMX_MB> -- npx -y mcp-matReplace <…> with your own values
Config file
{
"mcpServers": {
"mcp-mat": {
"command": "npx",
"args": [
"-y",
"mcp-mat"
],
"env": {
"MAT_HOME": "<MAT_HOME>",
"JAVA_PATH": "<JAVA_PATH>",
"MAT_XMX_MB": "<MAT_XMX_MB>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"mcp-mat": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-mat"
],
"env": {
"MAT_HOME": "<MAT_HOME>",
"JAVA_PATH": "<JAVA_PATH>",
"MAT_XMX_MB": "<MAT_XMX_MB>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e MAT_HOME=<MAT_HOME> -e JAVA_PATH=<JAVA_PATH> -e MAT_XMX_MB=<MAT_XMX_MB> mcp-mat npx -y mcp-matReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-mat
How do I install mcp-mat in Claude Code?
Run claude mcp add mcp-mat -- npx -y mcp-mat. To pass environment variables at the same time use claude mcp add --env MAT_HOME=<MAT_HOME> --env JAVA_PATH=<JAVA_PATH> --env MAT_XMX_MB=<MAT_XMX_MB> --transport stdio mcp-mat -- npx -y mcp-mat.
What does mcp-mat do?
It wraps Eclipse MAT in a headless MCP server, so the agent can run MAT reports, OQL queries, histograms, dominator tree and leak detection on a heap dump without the desktop UI.
Which commands need a second heap dump?
delta_histogram, leakhunter2, find_leaks2 and comparison_report require a baseline .hprof file to compare against.
