javaperf
Java profiling MCP via jcmd/jfr/jps. Diagnose performance, analyze threads, inspect JFR recordings.
Ask AI about javaperf
Powered by Claude Β· Grounded in docs
I know everything about javaperf. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
javaperf
MCP (Model Context Protocol) 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.
π¦ Install: npm install -g javaperf or use via npx
π npm: https://www.npmjs.com/package/javaperf
How to connect to Claude Desktop / IDE
Add the server to your MCP config. Example for claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"javaperf": {
"command": "npx",
"args": ["-y", "javaperf"]
}
}
}
For Cursor IDE: Settings β Features β Model Context Protocol β Edit Config, then add the same block inside mcpServers. See the Integration section for more options (local dev, custom JAVA_HOME, etc.).
Requirements
- Node.js v18+
- JDK 8u262+ or 11+ with JFR support
JDK tools (jps, jcmd, jfr) are auto-detected via JAVA_HOME or which java. If not found, set JAVA_HOME to your JDK root.
Quick Start
For Users (using npm package)
# No installation needed - use directly in Cursor/Claude Desktop
# Just configure it as described in Integration section below
For Developers
- Clone the repository:
git clone https://github.com/theSharque/mcp-jperf.git
cd mcp-jperf
- Install dependencies:
npm install
- Build the project:
npm run build
Usage
Development Mode
npm run dev
Production Mode
npm start
MCP Inspector
Debug and test with MCP Inspector:
npx @modelcontextprotocol/inspector node dist/index.js
Integration
Cursor IDE
- Open Cursor Settings β Features β Model Context Protocol
- Click "Edit Config" button
- Add one of the configurations below
Option 1: Via npm (Recommended)
Installs from npm registry automatically:
{
"mcpServers": {
"javaperf": {
"command": "npx",
"args": ["-y", "javaperf"]
}
}
}
Option 2: Via npm link (Development)
For local development with live changes:
{
"mcpServers": {
"javaperf": {
"command": "javaperf"
}
}
}
Requires: cd /path/to/mcp-jperf && npm link -g
Option 3: Direct path
{
"mcpServers": {
"javaperf": {
"command": "node",
"args": ["dist/index.js"],
"cwd": "${workspaceFolder}",
"env": {
"JAVA_HOME": "/path/to/your/jdk"
}
}
}
}
If list_java_processes fails with "jps not found", the MCP server may not inherit your shell's JAVA_HOME. Add the env block above with your JDK root path (e.g. /usr/lib/jvm/java-17 or ~/.sdkman/candidates/java/current).
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"javaperf": {
"command": "npx",
"args": ["-y", "javaperf"]
}
}
}
Continue.dev
Edit .continue/config.json:
{
"mcpServers": {
"javaperf": {
"command": "npx",
"args": ["-y", "javaperf"]
}
}
}
Tools
| Tool | Description |
|---|---|
list_java_processes | List running Java processes (pid, mainClass, args). Use topN (default 10) to limit. |
start_profiling | Start JFR recording with settings=profile. Pass pid, duration (seconds). Optional: memorysize (e.g. "20M"), stackdepth (default 128). |
list_jfr_recordings | List active JFR recordings for a process. Use before stop_profiling to get recordingId. |
stop_profiling | Stop recording and save to recordings/new_profile.jfr. Requires pid and recordingId. |
check_deadlock | Check for Java-level deadlocks. Returns structured JSON with threads, locks, and cycle. |
analyze_threads | Thread dump (jstack) with deadlock summary. Pass pid, optional topN (default 10). |
heap_histogram | Class histogram (GC.class_histogram). Pass pid, optional topN (20), all (triggers full GC β may pause app). |
heap_dump | Create .hprof heap dump for MAT/VisualVM. Pass pid. Saved to recordings/heap_dump.hprof. |
heap_info | Brief heap summary. Pass pid. |
vm_info | JVM info: uptime, version, flags. Pass pid. |
trace_method | Build call tree for a method from .jfr. Pass className, methodName. Optional: filepath (default new_profile), topN. |
parse_jfr_summary | Parse .jfr into summary: top methods, GC stats, anomalies. Optional: filepath (default new_profile), events, topN. |
profile_memory | Memory profile: top allocators, GC, potential leaks. Optional: filepath (default new_profile), topN. |
profile_time | CPU bottleneck profile (bottom-up). Optional: filepath (default new_profile), topN. |
profile_frequency | Call frequency profile (leaf frames). Optional: filepath (default new_profile), topN. |
Example Workflow
- List processes β
list_java_processes - Start recording β
start_profilingwithpidandduration(e.g. 60) - Wait for
durationseconds (or let it run) - Check recordings (optional) β
list_jfr_recordingsto getrecordingId - Stop and save β
stop_profilingwithpidandrecordingId - Analyze β Use
parse_jfr_summary,profile_memory,profile_time,profile_frequency, ortrace_method(filepath defaults to new_profile)
Limitations
- Sampling: JFR samples ~10ms; fast methods may not appear in ExecutionSample
- Local only: Runs on the machine where MCP is started
- Permissions: Must run as same user as target JVM for jcmd access
