Heap Seance MCP Server

@SegfaultSorcerer

Basic information

About Heap Seance MCP Server

Java memory leak diagnostics via MCP. Channels jcmd, jmap, jstat, JFR, Eclipse MAT, and async-profiler into a structured investigation workflow with confidence-based verdicts. Two slash commands: /leak-scan (conservative) and /leak-deep (full forensics). Designed for Claude Code.

#java#memory-leak#jvm#heap-dump#mcp #claude-code #diagnostics #profiling#eclipse-mat#async-profiler#jfr#garbage-collection

Heap Seance MCP Server config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "heap-seance": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/heap-seance",
        "python",
        "-m",
        "heap_seance_mcp.server"
      ],
      "env": {
        "JAVA_HOME": "/path/to/jdk-17",
        "MAT_BIN": "/path/to/ParseHeapDump.sh",
        "ASYNC_PROFILER_BIN": "/path/to/asprof"
      }
    }
  }
}

Heap Seance MCP Server tools

Tool list not available yet

This listing does not currently have a tool list to display. This does not mean the server has no tools; check its documentation for supported capabilities.

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is Heap Seance?

Heap Seance is an MCP server and CLI toolkit that integrates jcmd, jmap, jstat, jfr, Eclipse MAT, and async-profiler into a structured Java heap leak investigation workflow. It is designed to run inside Claude Code and provides two slash commands and eight MCP tools for conservative-to-deep leak analysis.

How to use Heap Seance?

Clone the repository, add a .mcp.json configuration to your Java project pointing to the Heap Seance directory, and copy the .claude/commands/ folder into the project. Then invoke the /leak-scan or /leak-deep slash commands from Claude Code, or use the CLI directly via uv run heap-seance --mode scan --match <name> or --mode deep --pid <pid>. The tools require Python 3.10+, JDK 17+, and uv. Deep mode additionally requires Eclipse MAT CLI.

Key features of Heap Seance

Two‑stage escalation: /leak-scan (conservative) then /leak-deep (full forensics)
Eight MCP tools: process listing, class histograms, GC snapshots, JFR recording, heap dumps, MAT leak suspects, and async-profiler allocation profiles
Unified confidence ladder: none → low → medium → high based on independent signals
Conservative by default: no deep forensics unless evidence demands it
Automatic artifact saving for team review
CLI mode available without Claude Code

Use cases of Heap Seance

Diagnosing Java memory leaks in production or staging environments
Identifying root holder chains and dominant retainers in heap dumps
Validating fix effectiveness by re‑scanning after code changes
Investigating growth patterns combined with GC pressure signals
Generating structured evidence for team reviews or incident reports

Frequently asked questions

What dependencies are required?

Python 3.10+, JDK 17+ for tooling (`jcmd`, `jmap`, `jstat`), and `uv` for environment management. Deep mode (`/leak-deep`) requires Eclipse MAT CLI. async‑profiler is optional.

Can Heap Seance analyze Java 8 target applications?

Yes, histogram, GC, and MAT work fully. JFR is skipped for Java 8 targets due to incompatible file format.

Where does Heap Seance save artifacts?

By default, artifacts (`.jfr`, `.hprof`, MAT reports) are saved to the system temporary directory. Override with the `HEAP_SEANCE_ARTIFACT_DIR` environment variable.

Is async-profiler required for deep mode?

No, async‑profiler is optional. Deep mode works without it, using JFR and MAT for evidence.

What Java version does the target application need?

The target application can run any Java version (including Java 8). The tooling JDK must be 17+.

Comments

More Other MCP servers

The Living Bread

A free remote MCP server for The Living Bread. Bible passages read word for word from a stored public domain text with an evidence label, keyword search and cross references, real churches, gatherings and prayer groups w