Headless MCP server for Eclipse MAT using direct java -jar org.eclipse.equinox.launcher_*.jar execution.
mat_healthcheck— Validate MAT launcher and Java runtime availabilitymat_parse_report— Run predefined MAT reports (leak suspects, system overview, etc.)mat_oql_query— Execute OQL queries and return inline resultsmat_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 dumpmat_oql_spec— Return OQL parser guidance and supported patterns
dominator_tree, show_dominator_tree, immediate_dominators, big_drops_in_dominator_tree
path2gc, merge_shortest_paths, gc_roots
histogram, delta_histogram*, list_objects, group_by_value, duplicate_classes
leakhunter, leakhunter2, find_leaks, find_leaks2, reference_leak
thread_overview, thread_details, thread_stack
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
references_statistics, weak_references_statistics, soft_references_statistics, phantom_references_statistics, finalizer_references_statistics
finalizer_overview, finalizer_thread, finalizer_queue, finalizer_in_processing, finalizer_thread_locals
show_retained_set, customized_retained_set
component_report, component_report_top, top_consumers, top_consumers_html, pie_biggest_objects
find_strings, waste_in_char_arrays
heap_dump_overview, unreachable_objects, system_properties, class_references, comparison_report*
bundle_registry, leaking_bundles
export_hprof
* Requires a baseline heap dump (second .hprof file).
- 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_reportwithorg.eclipse.mat.api:overviewand parseClass_Histogram*.txt. - For object inspection, use simple field-level OQL patterns (
INSTANCEOF,OBJECTS 0x...).
Required:
MAT_ALLOWED_ROOTS: comma-separated absolute directories where heap files are allowed.
Optional:
MAT_HOMEMAT_LAUNCHERJAVA_PATH(defaultjava)MAT_XMX_MB(default4096)MAT_TIMEOUT_SEC(default1800)MAT_CONFIG_DIR(default/tmp/mat-config)MAT_DATA_DIR(default/tmp/mat-workspace)MAT_DEBUG(defaultfalse)MAT_DEBUG_LOG_DIR(default/tmp/mcp-mat-logs)MAT_PRIVACY_MODE(defaultfalse)MAT_OQL_MAX_BYTES(default16384)MAT_RESULT_PREVIEW_LINES(default20)MAT_STDIO_TAIL_CHARS(default4000)
npm install
npm run build
MAT_ALLOWED_ROOTS=/absolute/heap/dir MAT_HOME=/path/to/mat node dist/src/server.js
npm test
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"
}
}
}
}
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"