Skip to main content
Glama
spark-profiler-mcp

spark-profiler-mcp

Official

spark-profiler-mcp

npm CI node license

MCP server that reads spark profiler files so an AI can give accurate Minecraft server tuning advice.

Parses spark's binary protobuf directly: no upload, no protoc. Ships a diagnose engine that knows TPS/MSPT/GC/heap thresholds and call-tree signatures (entity ticking, chunk gen, redstone, blocking I/O, plugin hogs, JVM flags), returns ranked findings with concrete fixes.

Supported files

File

spark command

Contents

.sparkprofile

/spark profiler --stop

Sampler / call tree

.sparkheap

/spark heapsummary --save-to-file

Memory (top retained types)

.sparkhealth

/spark health --save-to-file

TPS/MSPT/CPU/entities over time

Input = local path, https://spark.lucko.me/<key> / bytebin URL, or bare bytebin key. gzip and raw protobuf both auto-handled.

Shared spark.lucko.me links expire (bytebin deletes them). For permanent analysis, --save-to-file.

Most tools (diagnose, get_summary, get_platform_info, get_system_stats, get_health) work on sampler and health files. .sparkheap → get_heap_summary. Call-tree tools = sampler only.

Related MCP server: javaperf

Install (one line)

Published to npm — no clone, no build; npx fetches and runs it:

claude mcp add spark-profiler -- npx -y spark-profiler-mcp

Same thing as an MCP client config block (.mcp.json / claude_desktop_config.json):

{
  "mcpServers": {
    "spark-profiler": { "command": "npx", "args": ["-y", "spark-profiler-mcp"] }
  }
}

Then ask: "Load this.sparkprofile and tell me what to tune." The assistant calls load_profile → diagnose → drills in.

From source (dev / unpublished)

npm install && npm run build
claude mcp add spark-profiler -- node /absolute/path/to/spark-profiler-mcp/dist/index.js

Tools

Tool

Purpose

load_profile(source)

Parse file/URL/key → profileId + headline.

get_summary

Version, TPS, MSPT, heap, GC%, entities, hot methods, top plugins, verdict.

diagnose

Ranked findings: evidence → diagnosis → action.

get_platform_info

Brand/version, plugins, config highlights (view/sim-distance, spawn limits).

get_system_stats

Host CPU/RAM/disk/OS, Java, JVM args (secrets redacted), GC, Aikar check.

get_health

TPS 1/5/15m, MSPT percentiles, ping, heap, per-minute time-series (.sparkhealth).

get_world_stats

Entities, top types, per-world totals, data packs, game rules.

list_threads

Sampled threads, busiest first.

get_top_self_time

Hottest methods by self time (idle/native excluded).

get_sources_breakdown

Self-time per plugin/mod.

get_call_tree

Pruned tree. rootPath jumps to any frame.

search_call_tree

Find frames by substring or /regex/.

get_heap_summary

.sparkheap: largest retained types.

Token-cheap by design. Outputs = summaries + top-N. Full call tree never dumped. Reach it via get_call_tree (depth + minPercent capped) and search_call_tree. Parsed once, cached by profileId.

How it reads spark files

  • Vendored proto/spark/*.proto (from lucko/spark) loaded at runtime by protobufjs: no codegen.

  • .sparkprofile = SamplerData. Each thread = flattened call tree: ThreadNode.children is a flat pool, children_refs rebuild it. Self time = node total − Σ children. Native/idle frames flagged so the active hot path shows.

  • vmArgs surfaced for JVM analysis. Credential-like -D props redacted.

Development

npm run dev        # run from source (tsx)
npm test           # vitest: decode example, check analysis + diagnosis
npm run smoke      # end-to-end over stdio
npm run inspector  # @modelcontextprotocol/inspector

Publishing (maintainer)

Releases are automated via GitHub Actions + npm Trusted Publishing (OIDC) — no npm token is stored anywhere. One-time setup on npmjs.com: the package → Settings → Trusted Publisher → GitHub Actions, with Organization Imanity-Software, Repository spark-profiler-mcp, Workflow publish.yml. Then to cut a release:

# bump "version" in package.json, then:
git tag v0.1.1 && git push origin v0.1.1

.github/workflows/publish.yml builds, tests, and runs npm publish authenticated by OIDC, with provenance generated automatically. (Needs Node ≥ 22.14 + npm ≥ 11.5.1; the workflow upgrades npm itself.)

files ships only dist/ + proto/ (schemas are loaded at runtime, so they must be included); the 24 MB example and tests are excluded.

Manual fallback (no provenance): npm login && npm publish — prepublishOnly builds + tests first.

Prefer not to use npm at all? npx -y github:Imanity-Software/spark-profiler-mcp also works — the prepare hook builds it on install.

License

MIT. spark is © lucko, GPLv3. Only its .proto schemas are vendored here.

Available Tools

14 tools
diagnoseDiagnose performance issuesA

Apply the built-in interpretation knowledge base (TPS/MSPT/GC/heap/CPU thresholds, plugin dominance, entity/chunk/redstone/IO signatures, JVM-flag checks) and return ranked findings, each with evidence, diagnosis, and a concrete recommended action. This is the primary 'what should I tune' tool.

Inputs: profileId (required).

get_call_treeDrill into the call treeA

Pruned call tree for a thread. Children below minPercent of the thread total are dropped and depth is capped. Pass rootPath (an array of 'Class.method' labels/substrings) to descend into a specific subtree before expanding.

Inputs: profileId (required), thread, maxDepth, rootPath, +1 more.

get_healthTPS / MSPT / GC healthB

Tick health: TPS (1m/5m/15m), MSPT percentiles (mean/median/p95/max), ping, heap, GC analysis, and — for .sparkhealth reports (and the windows inside a sampler) — the per-minute time series with the worst windows highlighted.

Inputs: profileId (required), windowLimit.

get_heap_summaryHeap summary (.sparkheap)C

For a .sparkheap file: the largest retained types by size, with instance counts.

Inputs: profileId (required), topN.

get_platform_infoPlatform & pluginsA

Server brand/version, Minecraft version, the plugin/mod list with versions, config file names, and key config highlights (view/simulation-distance, spawn limits, etc.).

Inputs: profileId (required).

get_sources_breakdownPer-plugin breakdownA

Self-time grouped by plugin/mod source (spark 'sources' view) on a thread. excludeNative drops idle frames. Shows which plugin/mod owns the work.

Inputs: profileId (required), topN, thread, excludeNative.

get_summaryProfile summaryA

Headline health summary: server/MC version, TPS, MSPT, heap, GC%, entities, top hot methods & plugin sources, and the overall diagnosis verdict.

Inputs: profileId (required).

get_system_statsSystem & JVM statsA

Host CPU/RAM/disk/OS, Java version, JVM args (secrets redacted), detected GC, Xmx/Xms, and an Aikar's-flags check.

Inputs: profileId (required).

get_top_self_timeHottest methods (self time)B

Top methods by self-time on a thread (default 'Server thread'). excludeNative drops idle/native wait frames to reveal the hottest Java methods.

Inputs: profileId (required), topN, thread, excludeNative.

get_world_statsWorld & entitiesA

World/entity statistics: total entities, top entity types by count, per-world entity totals, data packs, non-default game rules.

Inputs: profileId (required), topN.

list_profilesList loaded profilesA

List the profiles currently loaded in memory (id, type, source).

Inputs: no named parameters.

list_threadsList sampled threadsA

List the sampled threads (name, total sampled ms, node count), busiest first. Use a name with the call-tree tools.

Inputs: profileId (required).

load_profileLoad a spark profileA

Load and parse a spark file from a local path, a bytebin/spark.lucko.me URL, or a bytebin key. Supports .sparkprofile (sampler), .sparkheap (memory), and .sparkhealth (health) files. Returns a profileId plus a headline summary; all other tools take that profileId.

Inputs: source (required).

search_call_treeSearch the call treeA

Find stack frames whose Class.method matches a substring or /regex/, returned with total/self time. Useful to check whether a suspected plugin/mechanic appears and how heavy it is.

Inputs: pattern (required), profileId (required), limit, thread.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 14 tools

    Disambiguation4/5

    Most tools target distinct aspects (health, call trees, heap, threads, etc.) with clear descriptions. Minor overlap between get_health and get_summary, and between get_top_self_time and get_sources_breakdown, but descriptions sufficiently differentiate them.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern using underscores (e.g., list_profiles, get_health, search_call_tree). Only 'diagnose' is a single word but fits the pattern. No mixing of styles.

    Tool Count5/5

    14 tools cover the core functionality of a spark profiler (loading, listing, health, call trees, heap, threads, system stats, diagnosis) without being excessive. Each tool has a clear purpose and earns its place.

    Completeness4/5

    The set covers the main analysis workflows: load, list, health, call trees, heap, threads, system info, and diagnosis. Missing a tool to clear/unload profiles, and no export or flame graph visualization, but core diagnostic needs are met.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP server for profiling Java applications via JDK utilities (jcmd, jfr, jps). Enables AI assistants to diagnose performance, analyze threads, and inspect JFR recordings without manual CLI usage.
      26
      63 npm
      10
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for profiling Python processes using py-spy, supporting flamegraphs, stack dumps, and performance comparisons.
      6
      22 PyPI
      3
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Hybrid TypeScript/Java MCP server for analyzing JVM Flight Recorder files, enabling AI agents to diagnose exceptions, slow SQL, network latency, and performance bottlenecks.
      -