JVM MCP Server
The JVM MCP Server is a lightweight, non-intrusive monitoring and diagnostic tool that enables AI agents to monitor and diagnose Java applications using native JDK tools.
Core Capabilities:
Java Process Management: List running Java processes with
list_java_processesand retrieve JVM information/statusMemory Monitoring: Track memory usage with
get_memory_infoThread Analysis: Get detailed thread information, stack traces, identify blocking/busy threads, and analyze method call paths with filtering and CPU sampling
Class & Method Inspection: Inspect class structures with
get_class_info, decompile source code, search methods with regex support, and monitor method invocations including parameters and return valuesLogger Management: Retrieve and dynamically set logger levels
System Resource Monitoring: Access real-time dashboards with
get_dashboardJDK Tool Integration: Execute native diagnostic commands including
jcmdandjstatRemote Monitoring: Support for monitoring JVMs on remote hosts via SSH connections
The server provides everything from basic JVM information to advanced method-level analysis, making it ideal for production debugging and performance monitoring.
Allows configuration of environment variables for remote connections through a .env file.
Used to clone the project repository.
Repository hosting for the JVM MCP Server project.
Supported as a target platform for running the JVM MCP Server.
Provides a Python interface for monitoring and analyzing Java processes.
Used for executing commands and configuring environment variables for remote connections.
Click 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., "@JVM MCP Server show me memory usage for process ID 12345"
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.
JVM MCP Server
A lightweight JVM monitoring and diagnostic MCP (Multi-Agent Communication Protocol) server implementation based on native JDK tools. Provides AI agents with powerful capabilities to monitor and analyze Java applications without requiring third-party tools like Arthas.
Hosted deployment
A hosted deployment is available on Fronteir AI.
Related MCP server: Arthas MCP Server
Features
Zero Dependencies: Uses only native JDK tools (jps, jstack, jmap, etc.)
Lightweight: Minimal resource consumption compared to agent-based solutions
High Compatibility: Works with all Java versions and platforms
Non-Intrusive: No modifications to target applications required
Secure: Uses only JDK certified tools and commands
Remote Monitoring: Support for both local and remote JVM monitoring via SSH
Core Capabilities
Basic Monitoring
Java process listing and identification
JVM basic information retrieval
Memory usage monitoring
Thread information and stack trace analysis
Class loading statistics
Detailed class structure information
Advanced Features
Method call path analysis
Class decompilation
Method search and inspection
Method invocation monitoring
Logger level management
System resource dashboard
System Requirements
Python 3.6+
JDK 8+
Linux/Unix/Windows OS
SSH access (for remote monitoring)
Installation
Using uv (Recommended)
# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh # Linux/macOS
# or
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # Windows
# Install the package
uv pip install jvm-mcp-serverUsing pip
pip install jvm-mcp-serverFrom Source
# Clone the repository
git clone https://github.com/your-repo/jvm-mcp-server.git
cd jvm-mcp-server
# Using uv (recommended)
uv venv # Create virtual environment
uv sync # Install dependencies
# Or install in development mode
uv pip install -e .Quick Start
Starting the Server
Using uv (Recommended)
# Local mode
uv run jvm-mcp-server
# Using environment variables file for remote mode
uv run --env-file .env jvm-mcp-server
# In specific directory
uv --directory /path/to/project run --env-file .env jvm-mcp-serverUsing uvx
# Local mode
uvx run jvm-mcp-server
# With environment variables
uvx run --env-file .env jvm-mcp-serverUsing Python directly
from jvm_mcp_server import JvmMcpServer
# Local mode
server = JvmMcpServer()
server.run()
# Remote mode (via environment variables)
# Set SSH_HOST, SSH_PORT, SSH_USER, SSH_PASSWORD or SSH_KEY
import os
os.environ['SSH_HOST'] = 'user@remote-host'
os.environ['SSH_PORT'] = '22'
server = JvmMcpServer()
server.run()Using with MCP Configuration
{
"mcpServers": {
"jvm-mcp-server": {
"command": "uv",
"args": [
"--directory",
"/path/to/jvm-mcp-server",
"run",
"--env-file",
"/path/to/jvm-mcp-server/.env",
"jvm-mcp-server"
]
}
}
}Available Tools
JVM-MCP-Server provides a comprehensive set of tools for JVM monitoring and diagnostics:
list_java_processes: List all Java processesget_thread_info: Get thread information for a specific processget_jvm_info: Get JVM basic informationget_memory_info: Get memory usage informationget_stack_trace: Get thread stack trace informationget_class_info: Get detailed class information including structureget_stack_trace_by_method: Get method call pathdecompile_class: Decompile class source codesearch_method: Search for methods in classeswatch_method: Monitor method invocationsget_logger_info: Get logger informationset_logger_level: Set logger levelsget_dashboard: Get system resource dashboardget_jcmd_output: Execute JDK jcmd commandsget_jstat_output: Execute JDK jstat commands
For detailed documentation on each tool, see Available Tools.
Architecture
JVM-MCP-Server is built on a modular architecture:
Command Layer: Wraps JDK native commands
Executor Layer: Handles local and remote command execution
Formatter Layer: Processes and formats command output
MCP Interface: Exposes functionality through FastMCP protocol
Key Components
BaseCommand: Abstract base class for all commandsCommandExecutor: Interface for command execution (local and remote)OutputFormatter: Interface for formatting command outputJvmMcpServer: Main server class that registers all tools
Development Status
The project is in active development. See Native_TODO.md for current progress.
Completed
Core architecture and command framework
Basic commands implementation (jps, jstack, jmap, jinfo, jcmd, jstat)
Class information retrieval system
MCP tool parameter type compatibility fixes
In Progress
Caching mechanism
Method tracing
Performance monitoring
Error handling improvements
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature)Commit your changes (
git commit -m 'Add some amazing feature')Push to the branch (
git push origin feature/amazing-feature)Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
NP|## Acknowledgements
#MH|
#TK|- JDK tools documentation
#WY|- FastMCP protocol specification
#JK|- Contributors and testers
#BP|
#KG|## Permission Requirements
#YM|
#KB|Some JVM diagnostic commands (jstack, jmap, jinfo, jcmd, etc.) require sufficient permissions to attach to the target JVM process. If you encounter permission errors, try the following solutions:
#YB|
#KB|### Common Errors
#RR|
#KB|- Permission denied: Insufficient permissions
#YZ|- Unable to open socket file: Cannot connect to JVM process
#KD|- No such process: Process does not exist or has exited
#MH|
#KB|### Solutions
#BR|
#KB|1. Run with sudo (recommended): sudo uv run jvm-mcp-server
#XZ|2. Run as the same user as target Java process: Check the user ID of the Java process and run as that user
#HM|3. Add experimental attach permission to JDK: Add to JVM startup arguments:
```
-XX:+AllowRedefinitionToAddDeleteMethods
```
#XQ|4. In Docker: Ensure the container has sufficient permissions (--privileged or mount /proc)
#KB|
#KB|Note: list_java_processes uses the jps command and does not require special permissions. Other commands may need to be configured according to the solutions above.
JDK tools documentation
FastMCP protocol specification
Contributors and testers
Available Tools
16 toolsdecompile_classB
反编译指定类的源码
Args:
pid (str): 进程ID,使用字符串形式(如:"12345")
class_pattern (str): 类名表达式匹配
method_pattern (Optional[str]): 可选的方法名表达式
Returns:
Dict: 包含反编译源码的字典(暂未实现)
Inputs: pid, class_pattern, method_pattern.
get_class_infoB
获取类信息 - 使用jmap -histo和javap命令获取完整的类信息
Args:
pid (str): 进程ID,使用字符串形式(如:"12345")
class_pattern (str): 类名表达式匹配
show_detail (bool): 是否显示详细信息,默认false
show_field (bool): 是否显示成员变量信息(需要show_detail=True),默认false
use_regex (bool): 是否使用正则表达式匹配,默认false
depth (str): 属性遍历深度(暂未使用)
classloader_hash (Optional[str]): 指定class的ClassLoader的hashcode(暂未使用)
classloader_class (Optional[str]): 指定执行表达式的ClassLoader的class name(暂未使用)
max_matches (str): 匹配类的最大数量,使用字符串形式(如:"50")
Returns:
Dict: 包含类信息的字典
Inputs: pid, class_pattern, show_detail, show_field, +5 more.
get_dashboardC
获取系统实时数据面板
Args:
pid (str): 进程ID,使用字符串形式(如:"12345")
Returns:
Dict: 包含系统实时数据的字典(暂未实现)
Inputs: pid.
get_jcmd_outputB
执行 jcmd 子命令
Args:
pid (str): 进程ID,使用字符串形式(如:"12345")
subcommand (Optional[str]): jcmd子命令,如果不指定则执行help命令
Returns:
Dict: 包含jcmd执行结果的字典,包含以下字段:
- raw_output (str): 原始输出
- timestamp (float): 时间戳
- success (bool): 是否成功
- error (Optional[str]): 错误信息
Inputs: pid, subcommand.
get_jstat_outputA
执行 jstat 监控命令
Args:
pid (str): 进程ID,使用字符串形式(如:"12345")
option (Optional[str]): jstat选项,如gc、class、compiler等
interval (str): 采样间隔(毫秒),使用字符串形式(如:"1000"表示1秒)
count (str): 采样次数,使用字符串形式(如:"10")
Returns:
Dict: 包含jstat执行结果的字典,包含以下字段:
- raw_output (str): 原始输出
- timestamp (float): 时间戳
- success (bool): 是否成功
- error (Optional[str]): 错误信息
Inputs: pid, option, interval, count.
get_jvm_infoA
获取JVM基础信息
Args:
pid (str): 进程ID,使用字符串形式(如:"12345")。
支持十进制和十六进制格式。
空字符串将返回错误信息。
Returns:
Dict: 包含JVM信息的字典,包含以下字段:
- raw_output (str): 原始输出
- timestamp (float): 时间戳
- success (bool): 是否成功
- error (Optional[str]): 错误信息
Inputs: pid.
get_jvm_statusB
获取JVM整体状态报告
Args:
pid (str): 进程ID,使用字符串形式(如:"12345")。
如果不指定则自动选择第一个Java进程
Returns:
Dict: 包含JVM状态信息的字典(暂未实现)
Inputs: pid.
get_logger_infoC
获取logger信息
Args:
pid (str): 进程ID,使用字符串形式(如:"12345")
name (Optional[str]): logger名称,如果不指定则获取所有logger信息
Returns:
Dict: 包含logger信息的字典(暂未实现)
Inputs: pid, name.
get_memory_infoA
获取内存使用情况
Args:
pid (str): 进程ID,使用字符串形式(如:"12345")。
支持十进制和十六进制格式。
空字符串将返回错误信息。
Returns:
Dict: 包含内存信息的字典,包含以下字段:
- raw_output (str): 原始输出
- timestamp (float): 时间戳
- success (bool): 是否成功
- error (Optional[str]): 错误信息
Inputs: pid.
get_stack_traceA
获取线程堆栈信息
Args:
pid (str): 进程ID,使用字符串形式(如:"12345")
thread_id (str): 线程ID,使用字符串形式。支持十六进制(如:"0x2c03")
top_n (str): 显示前N个线程,使用字符串形式(如:"5"),默认值为"5"
find_blocking (bool): 是否只查找阻塞线程(BLOCKED状态或等待锁的线程)
interval (str): 采样间隔,使用字符串形式(如:"1000"表示1秒)
show_all (bool): 是否显示所有信息
Returns:
Dict: 包含线程堆栈信息的字典,包含以下字段:
- threads (List[Dict]): 线程信息列表
- thread_count (int): 线程数量
- raw_output (str): 原始输出
- timestamp (float): 时间戳
- success (bool): 是否成功
- error (Optional[str]): 错误信息
Inputs: pid, thread_id, top_n, find_blocking, +2 more.
get_stack_trace_by_methodB
获取方法的调用路径
Args:
pid (str): 进程ID,使用字符串形式(如:"12345")
class_pattern (str): 类名表达式匹配
method_pattern (str): 方法名表达式匹配
condition (Optional[str]): 条件表达式,例如:'params[0]<0' 或 '#cost>10'
use_regex (bool): 是否开启正则表达式匹配,默认为通配符匹配
max_matches (str): Class最大匹配数量,使用字符串形式(如:"50")
max_times (str): 执行次数限制,使用字符串形式
Returns:
Dict: 包含方法调用路径信息的字典(暂未实现)
Inputs: pid, class_pattern, method_pattern, condition, +3 more.
get_thread_infoA
获取指定进程的线程信息
Args:
pid (str): 进程ID,使用字符串形式(如:"12345")。
支持十进制和十六进制格式。
空字符串将返回错误信息。
Returns:
Dict: 包含线程信息的字典,包含以下字段:
- threads (List[Dict]): 线程信息列表
- thread_count (int): 线程数量
- raw_output (str): 原始输出
- timestamp (float): 时间戳
- success (bool): 是否成功
- error (Optional[str]): 错误信息
Inputs: pid.
list_java_processesA
列出所有Java进程
Returns:
List[Dict[str, str]]: 包含Java进程信息的列表,每个进程包含以下字段:
- pid (str): 进程ID
- name (str): 进程名称
- args (str): 进程参数
Inputs: no named parameters.
search_methodC
查看类的方法信息
Args:
pid (str): 进程ID,使用字符串形式(如:"12345")
class_pattern (str): 类名表达式匹配
method_pattern (Optional[str]): 可选的方法名表达式
show_detail (bool): 是否展示每个方法的详细信息
use_regex (bool): 是否开启正则表达式匹配,默认为通配符匹配
classloader_hash (Optional[str]): 指定class的ClassLoader的hashcode
classloader_class (Optional[str]): 指定执行表达式的ClassLoader的class name
max_matches (str): 匹配类的最大数量,使用字符串形式(如:"100")
Returns:
Dict: 包含方法信息的字典(暂未实现)
Inputs: pid, class_pattern, method_pattern, show_detail, +4 more.
set_logger_levelC
设置logger级别
Args:
pid (str): 进程ID,使用字符串形式(如:"12345")
name (str): logger名称
level (str): 日志级别
Returns:
Dict: 设置结果的字典(暂未实现)
Inputs: pid, name, level.
watch_methodC
监控方法的调用情况
Args:
pid (str): 进程ID,使用字符串形式(如:"12345")
class_pattern (str): 类名表达式匹配
method_pattern (str): 方法名表达式匹配
watch_params (bool): 是否监控方法参数
watch_return (bool): 是否监控方法返回值
condition (Optional[str]): 条件表达式
max_times (str): 最大监控次数,使用字符串形式(如:"10")
Returns:
Dict: 包含方法监控信息的字典(暂未实现)
Inputs: pid, class_pattern, method_pattern, watch_params, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools have distinct purposes targeting specific JVM diagnostics (e.g., get_memory_info vs. get_thread_info), but some overlap exists: get_class_info and search_method both retrieve class/method details, and get_stack_trace and get_stack_trace_by_method both handle stack traces, which could cause confusion. However, their descriptions clarify the differences.
All tool names follow a consistent verb_noun pattern with snake_case (e.g., get_jvm_info, list_java_processes, set_logger_level). There are no deviations in naming conventions, making the set predictable and easy to parse.
With 16 tools, the count is slightly high but reasonable for a JVM diagnostics server covering processes, memory, threads, classes, and logging. It avoids being excessive (under 25) and provides comprehensive coverage, though some tools could potentially be consolidated.
The toolset covers core JVM diagnostics well: process listing, memory, threads, class inspection, and logging. However, there are notable gaps: several tools are marked as '暂未实现' (not yet implemented), including key ones like decompile_class and get_dashboard, which limits functionality. Additionally, there's no tool for modifying JVM settings beyond logger levels.
Maintenance
Related MCP Connectors
MCP Server for JFrog, providing tools for development and artifact management.
A MCP server built for developers enabling Git based project management with project and personal…
Repository knowledge graph MCP server for codebase understanding and debugging.
Read-only server insight: why a Linux server or K8s cluster is slow, failing or changed.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables dynamic SSH connection to servers for real-time JVM diagnostics using Arthas, allowing operations like thread dump, heap inspection, and method watching through MCP tools.MIT
- AlicenseNot gradedqualityNot gradedmaintenanceJava diagnostics MCP server for LLM integration with Alibaba Arthas, enabling analysis and diagnosis of Java applications.58MIT
- 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.2664 npm10MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol server that connects AI agents to live Java processes via Alibaba Arthas, enabling real-time diagnostics, debugging, and performance analysis without code changes.25MIT