Java Heap Dump MCP Server

A Model Context Protocol (MCP) server for analyzing Java heap dump files (.hprof). This project provides a set of tools that allow AI assistants to analyze Java heap dumps through a standardized MCP interface. Based on NetBeans Profiler library as a backend.

Features

• Load Heap Dumps - Parse and load .hprof heap dump files
• Query Classes - Get classes sorted by instance count/size, search by name, or use regex patterns with pagination
• Analyze Instances - Find biggest objects by retained size, get instance details with field values
• References - Get all references to an instance
• GC Root Analysis - View garbage collection roots with pagination
• Heap Summary - Get overview statistics of the heap
• System Properties - Access JVM system properties from the heap dump
• OQL Support - Execute Object Query Language queries on the heap
• Reflection-based Tools - Tools are automatically generated from annotated methods

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      MCP Client (AI)                        │
└─────────────────────────┬───────────────────────────────────┘
                          │ MCP Protocol (JSON-RPC)
┌─────────────────────────▼───────────────────────────────────┐
│                    MCP Server                               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              HeapDumpTools (MCP Adapter)           │    │
│  └─────────────────────────┬─────────────────────────┘    │
└────────────────────────────┼────────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────────┐
│                 HeapDumpService (Core)                     │
│  ┌──────────────────────────────────────────────────────┐   │
│  │         NetBeans Profiler Heap Analysis API          │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Available Tools

Requirements

• Java 17 or higher
• Maven 3.6+

Installing

• Just download jar from the releases section

Building

mvn clean package

This creates a shaded JAR at target/heap_mcp_nb-1.0-SNAPSHOT-shaded.jar with all dependencies included.

Running

As MCP Server (STDIO)

java -jar target/heap_mcp_nb-0.0.1.jar

The server communicates via STDIO, making it compatible with MCP clients like Claude Desktop or opencode.

Configuration

For opencode

Add to your opencode.json:

{
  "mcpServers": {
    "heap-analyzer": {
      "command": "java",
      "args": ["-jar", "${workspace}/target/heap_mcp_nb-0.0.1.jar"],
      "env": {}
    }
  }
}

For Claude Desktop

{
  "mcpServers": {
    "heap-analyzer": {
      "command": "java",
      "args": ["-jar", "path/to/heap_mcp_nb-0.0.1.jar"],
      "env": {}
    }
  }
}

Running Tests

mvn test

To run specific tests:

mvn test -Dtest=HeapDumpMcpTest
mvn test -Dtest=McpClientIntegrationTest

Usage Examples

In tools like Trae, OpenCode or Qwen CLI you can just point to .hrpof file with your heap dump and ask smth like Find possible problems in this heap dump

Using with MCP Client

// Create service and tools
HeapDumpService service = new HeapDumpService();
HeapDumpTools tools = new HeapDumpTools(service);

// Load heap dump
CallToolRequest loadRequest = new CallToolRequest("load_heap", Map.of("file_path", "/path/to/heapdump.hprof"));
tools.loadHeapTool().callHandler().apply(null, loadRequest);

// Get top classes by instance count
CallToolRequest classesRequest = new CallToolRequest("get_classes_by_max_instances_count", Map.of("from", 0, "to", 50));
CallToolResult result = tools.getClassesByMaxInstancesCountTool().callHandler().apply(null, classesRequest);

Tool Response Format

Most tools return results as newline-separated text. For example:

get_class_by_name:
Name: java.util.HashMap
Instances: 152
Total Size: 24320
Superclass: java.util.AbstractMap
Static Fields:
  int DEFAULT_INITIAL_CAPACITY = 16
  float loadFactor = 0.75 (Instance ID: 123456789)
Fields:
  java.util.HashMap$Node[] table
  int size
  int threshold
  float loadFactor

Reflection-based Tool Factory

Tools can also be created dynamically using the ToolsFactory class with annotations:

@Tool(name = "my_tool", title = "My Tool", description = "Does something")
public String myToolMethod(
    @Required("param1") String param1,
    @Default(name = "param2", value = "50") int param2) {
    // implementation
}

See src/main/java/com/onpositive/analyzer/mcp/reflection/ for the annotation definitions.

Dependencies

• io.modelcontextprotocol.sdk:mcp (1.0.0) - MCP Java SDK
• org.netbeans.modules:org-netbeans-lib-profiler (RELEASE200) - Heap analysis
• org.netbeans.modules:org-netbeans-modules-profiler-oql (RELEASE200) - OQL engine
• JUnit 5 - Testing framework

License

MIT License