spark-profiler-mcp
OfficialClick on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@spark-profiler-mcp Analyze my server's spark profile for performance issues"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
spark-profiler-mcp
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 |
|
| Sampler / call tree |
|
| Memory (top retained types) |
|
| 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.melinks 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-mcpSame 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.jsTools
Tool | Purpose |
| Parse file/URL/key → |
| Version, TPS, MSPT, heap, GC%, entities, hot methods, top plugins, verdict. |
| Ranked findings: evidence → diagnosis → action. |
| Brand/version, plugins, config highlights (view/sim-distance, spawn limits). |
| Host CPU/RAM/disk/OS, Java, JVM args (secrets redacted), GC, Aikar check. |
| TPS 1/5/15m, MSPT percentiles, ping, heap, per-minute time-series ( |
| Entities, top types, per-world totals, data packs, game rules. |
| Sampled threads, busiest first. |
| Hottest methods by self time (idle/native excluded). |
| Self-time per plugin/mod. |
| Pruned tree. |
| Find frames by substring or |
|
|
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 byprotobufjs: no codegen..sparkprofile=SamplerData. Each thread = flattened call tree:ThreadNode.childrenis a flat pool,children_refsrebuild it. Self time = node total − Σ children. Native/idle frames flagged so the active hot path shows.vmArgssurfaced for JVM analysis. Credential-like-Dprops 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/inspectorPublishing (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 toolsdiagnoseDiagnose 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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
Analytics and debugging for your MCP server — explore usage and sessions, then root-cause errors.
BeautySpark MCP server for ChatGPT, Claude and other MCP clients
2,000+ MCP servers read at source level. Know what one does before you connect. Free, no key.
Market data tools for the MCP ecosystem: server stats, events, search, leaderboards, package trends.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server that optimizes Apache Spark code using Claude AI, providing intelligent code optimization suggestions and performance analysis.29-
- AlicenseAqualityCmaintenanceMCP 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.2663 npm10MIT
- AlicenseAqualityCmaintenanceMCP server for profiling Python processes using py-spy, supporting flamegraphs, stack dumps, and performance comparisons.622 PyPI3MIT
- FlicenseNot gradedqualityDmaintenanceHybrid TypeScript/Java MCP server for analyzing JVM Flight Recorder files, enabling AI agents to diagnose exceptions, slow SQL, network latency, and performance bottlenecks.-