MAT

•
24
•

Provides a headless server for programmatic execution of Eclipse Memory Analyzer Tool (MAT) commands and OQL queries.

This tool serves as a headless server, enabling programmatic interaction with the powerful Eclipse Memory Analyzer Tool (MAT). It allows for the automation of heap dump analysis, generation of predefined reports, execution of custom OQL queries, and utilization of a wide range of built-in MAT analysis commands. Designed for integration into development workflows and environments like Claude Code and Codex, it empowers developers to streamline memory leak detection, performance optimization, and in-depth heap analysis without relying on the MAT GUI.

Key Features

01Access 56 built-in MAT analysis commands including histogram, dominator tree, and thread overview
025 GitHub stars
03Validate MAT launcher and Java runtime availability for heap dump analysis
04Run predefined MAT reports like leak suspects and system overviews
05Check the status of MAT index artifacts for any given heap dump
06Execute Object Query Language (OQL) queries on heap dumps for detailed insights

Use Cases

01Automate heap dump analysis within CI/CD pipelines for continuous performance monitoring
02Integrate advanced memory analysis capabilities directly into development environments like Claude Code or Codex
03Programmatically query and analyze heap dumps to identify memory leaks and performance bottlenecks

mcp-mat

Headless MCP server for Eclipse MAT using direct java -jar org.eclipse.equinox.launcher_*.jar execution.

Features

  • mat_healthcheck — Validate MAT launcher and Java runtime availability
  • mat_parse_report — Run predefined MAT reports (leak suspects, system overview, etc.)
  • mat_oql_query — Execute OQL queries and return inline results
  • mat_run_command — Execute 56 built-in MAT analysis commands (histogram, dominator_tree, path2gc, thread_overview, etc.)
  • mat_index_status — Check whether MAT index artifacts exist for a heap dump
  • mat_oql_spec — Return OQL parser guidance and supported patterns

Supported Commands (mat_run_command)

Dominator tree analysis

dominator_tree, show_dominator_tree, immediate_dominators, big_drops_in_dominator_tree

Path to GC roots

path2gc, merge_shortest_paths, gc_roots

Histogram & object listing

histogram, delta_histogram*, list_objects, group_by_value, duplicate_classes

Leak detection

leakhunter, leakhunter2, find_leaks, find_leaks2, reference_leak

Thread analysis

thread_overview, thread_details, thread_stack

Collection analysis

collection_fill_ratio, collections_grouped_by_size, array_fill_ratio, arrays_grouped_by_size, hash_entries, map_collision_ratio, extract_list_values, hash_set_values, primitive_arrays_with_a_constant_value

Reference analysis

references_statistics, weak_references_statistics, soft_references_statistics, phantom_references_statistics, finalizer_references_statistics

Finalizer analysis

finalizer_overview, finalizer_thread, finalizer_queue, finalizer_in_processing, finalizer_thread_locals

Retained set

show_retained_set, customized_retained_set

Component & top consumers

component_report, component_report_top, top_consumers, top_consumers_html, pie_biggest_objects

String & memory waste

find_strings, waste_in_char_arrays

Heap info & misc

heap_dump_overview, unreachable_objects, system_properties, class_references, comparison_report*

Eclipse/OSGi specific

bundle_registry, leaking_bundles

Export

export_hprof

* Requires a baseline heap dump (second .hprof file).

OQL mode notes

  • This server normalizes client OQL input and wraps it for MAT parse-app command mode.
  • You can send OQL with or without outer quotes.
  • For class ranking and top consumers, prefer mat_parse_report with org.eclipse.mat.api:overview and parse Class_Histogram*.txt.
  • For object inspection, use simple field-level OQL patterns (INSTANCEOF, OBJECTS 0x...).

Environment

Required:

  • MAT_ALLOWED_ROOTS: comma-separated absolute directories where heap files are allowed.

Optional:

  • MAT_HOME
  • MAT_LAUNCHER
  • JAVA_PATH (default java)
  • MAT_XMX_MB (default 4096)
  • MAT_TIMEOUT_SEC (default 1800)
  • MAT_CONFIG_DIR (default /tmp/mat-config)
  • MAT_DATA_DIR (default /tmp/mat-workspace)
  • MAT_DEBUG (default false)
  • MAT_DEBUG_LOG_DIR (default /tmp/mcp-mat-logs)
  • MAT_PRIVACY_MODE (default false)
  • MAT_OQL_MAX_BYTES (default 16384)
  • MAT_RESULT_PREVIEW_LINES (default 20)
  • MAT_STDIO_TAIL_CHARS (default 4000)

Run

npm install
npm run build
MAT_ALLOWED_ROOTS=/absolute/heap/dir MAT_HOME=/path/to/mat node dist/src/server.js

Test

npm test

Install in Claude Code

Add the MCP server to Claude Code settings (~/.claude/settings.json or project .claude/settings.json):

{
  "mcpServers": {
    "mat": {
      "command": "node",
      "args": ["/path/to/mcp-mat/dist/src/server.js"],
      "env": {
        "MAT_ALLOWED_ROOTS": "/ABS/PATH/TO/HEAP_DUMPS",
        "MAT_HOME": "/Applications/MemoryAnalyzer.app/Contents/Eclipse"
      }
    }
  }
}

Install in Codex

Build first:

cd /path/to/mcp-mat
npm install
npm run build

Add MCP server to Codex:

codex mcp add \
  --env MAT_ALLOWED_ROOTS=/ABS/PATH/TO/HEAP_DUMPS \
  --env MAT_HOME=/Applications/MemoryAnalyzer.app/Contents/Eclipse \
  mat \
  node /path/to/mcp-mat/dist/src/server.js

Verify:

codex mcp list
codex mcp get mat --json

If you need to update the entry:

codex mcp remove mat
# then run codex mcp add ... again

Equivalent ~/.codex/config.toml entry:

[mcp_servers.mat]
command = "node"
args = ["/path/to/mcp-mat/dist/src/server.js"]

[mcp_servers.mat.env]
MAT_ALLOWED_ROOTS = "/ABS/PATH/TO/HEAP_DUMPS"
MAT_HOME = "/Applications/MemoryAnalyzer.app/Contents/Eclipse"