JVM Monitoring MCP Server

Developer ToolsPython

Monitor and analyze Java processes using Arthas

Available Tools

list_java_processes

Lists all running Java processes on the target system

get_thread_info

Retrieves detailed thread information from a Java process

pid

get_memory_info

Retrieves memory usage information from a Java process

pid

get_stack_trace

Retrieves stack trace information for threads in a Java process

pidthread_name

get_class_info

Retrieves information about loaded classes in a Java process

pidclass_pattern

decompile_class

Decompiles a Java class from a running process

pidclass_name

decompile_method

Decompiles a specific method from a Java class

pidclass_namemethod_name

monitor_method

Monitors method calls in a Java process

pidclass_patternmethod_pattern

change_log_level

Dynamically changes the log level for a logger in a Java process

pidlogger_namelevel

JVM Monitoring provides a comprehensive interface for monitoring and analyzing Java applications. Built on top of the powerful Arthas diagnostic tool, it enables developers and operations teams to inspect running Java processes, monitor JVM performance metrics, and troubleshoot issues in both local and remote environments. This tool bridges the gap between AI assistants and the Java ecosystem, allowing for real-time analysis of thread states, memory usage, class information, and method execution. With support for both local and remote Java processes, it's a versatile solution for Java application monitoring and debugging.

Overview

JVM Monitoring is a Model Context Protocol (MCP) server that provides AI assistants with the ability to monitor and analyze Java applications. It leverages Arthas, a powerful Java diagnostic tool, to offer deep insights into running JVM processes.

System Requirements

Python 3.10 or higher
Java Runtime Environment (JRE) 8 or higher
Network connection (for downloading Arthas if not already present)
SSH access to target server (only if using remote mode)

Installation

Step 1: Install the UV Package Manager

First, you need to install the UV package manager, which is used to manage the Python environment:

Linux/macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Alternatively, you can install UV using pip:

pip install uv

Step 2: Clone the Repository

git clone https://github.com/xzq-xu/jvm-mcp-server.git
cd jvm-mcp-server

Step 3: Set Up the Environment

# Create virtual environment
uv venv

# Install dependencies
uv sync

Step 4: Configure for Remote Connections (Optional)

If you want to monitor Java processes on a remote server, create a .env file in the project directory with the following content:

ARTHAS_SSH_HOST=user@remote-host
ARTHAS_SSH_PORT=22  # Optional, default is 22
ARTHAS_SSH_PASSWORD=your-password  # If using password authentication

Usage

Starting the Server

Local Mode:

uv run jvm-mcp-server

Remote Mode (with environment file):

uv run --env-file .env jvm-mcp-server

Integration with AI Assistants

To use JVM Monitoring with AI assistants, you need to configure the MCP server in your AI assistant's configuration. The server will automatically download and manage the Arthas tool if it's not already present.

When first connecting to a Java process, the server will attach Arthas to it, allowing for non-intrusive monitoring and analysis.

Configuration Options

Local Mode: Monitors Java processes running on the same machine as the MCP server
Remote Mode: Connects to a remote server via SSH to monitor Java processes
Process Selection: Automatically lists available Java processes for monitoring
Custom Commands: Supports executing custom Arthas commands for advanced diagnostics

Troubleshooting

Connection Issues: Ensure SSH credentials are correct for remote connections
Permission Errors: The user running the server must have permissions to access the target Java processes
Java Version Compatibility: Ensure the Java version on the target system is compatible with Arthas (JRE 8+)
Network Connectivity: For remote mode, ensure proper network connectivity and that SSH port is accessible

Security Considerations

The server requires access to Java processes, which may contain sensitive information
For production environments, carefully evaluate the security implications
Consider using SSH key-based authentication instead of passwords for remote connections
Limit access to the server to trusted users and systems