Memory Analyzer MCP Server

MCP server for JVM heap dump (.hprof) analysis powered by Eclipse MAT. Enables AI agents (Claude Code, Cursor, etc.) to autonomously investigate OutOfMemoryError issues.

Quick Start

Requirements: Java 21+, Node.js 18+ (for npx)

Add to your project's .mcp.json:

{
  "mcpServers": {
    "memory-analyzer": {
      "command": "npx",
      "args": ["-y", "jvm-heap-dump-mcp"]
    }
  }
}

Restart Claude Code. The MCP handshake completes instantly; the JAR (~28 MB) downloads in the background on first use. Tools become available via notifications/tools/list_changed once the download finishes (~30–60 seconds on a typical connection). If an agent calls a tool before the JAR is ready, it will get a clear "still initializing" error and can retry.

Pre-downloading the JAR (recommended on slow or corporate networks)

You can warm the cache explicitly before starting your MCP client. This runs the download synchronously in your terminal with visible progress and a clear error if something fails (SSL, proxy, etc.):

npx -y jvm-heap-dump-mcp --prepare

Once it prints Done. JAR cached at ..., every subsequent MCP server startup is instant. The JAR lives in ~/.cache/jvm-heap-dump-mcp/ keyed by version, so running --prepare after upgrading to a new version pre-downloads the new JAR without touching the old one.

If a download gets interrupted (network drop, you kill the process, Claude Code restarts mid-download), the next --prepare or MCP startup resumes from where it stopped via HTTP Range — no need to re-download the ~28 MB from zero.

What It Does

Ask your AI agent to analyze a heap dump:

"Open the heap dump at /tmp/oom.hprof and find what's causing the OOM"

The agent will use the tools to:

1. Open the dump and get a summary (heap size, object count)
2. Dominator tree to find objects retaining the most memory
3. Drill down into the largest retainers
4. Path to GC roots to understand why objects can't be garbage collected
5. Threads with stack traces to see what was happening at the time of OOM
6. Close the dump when done

Tools

Updating

npx caches the package locally. To update to the latest version:

npx -y jvm-heap-dump-mcp@latest

The JAR for each version is cached separately under ~/.cache/jvm-heap-dump-mcp/, so upgrading only re-downloads the JAR if the version changed.

Troubleshooting

"Still initializing" errors that don't go away: the background download might be repeatedly getting killed. Run npx -y jvm-heap-dump-mcp --prepare in a terminal — you'll see the real error (network, SSL, proxy) in plain text. It also resumes from any partial .downloading file in ~/.cache/jvm-heap-dump-mcp/ instead of starting over.

**"Failed to reconnect" after

... View full README on GitHub