Arthas JVM Diagnostics MCP server for AI agents

This server implementation allows you to monitor and analyze Java processes using the Model Context Protocol (MCP) based on Arthas. It provides an interface for JVM monitoring with features like thread tracking, memory usage analysis, and performance diagnostics.

System Requirements

Python 3.10+
Java Runtime Environment (JRE) 8+
Network connection (for downloading Arthas)
SSH access to target server (if using remote mode)

Installation

Install the UV Tool

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

# Or install using pip
pip install uv

# Or install using pipx (if you have pipx installed)
pipx install uv 

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

Set Up the Project

# Clone the repository
git clone https://github.com/xzq-xu/jvm-mcp-server.git
cd jvm-mcp-server

# Create virtual environment
uv venv

# Sync project dependencies
uv sync

Configure Remote Connections (Optional)

Create a .env file and add the following configurations for remote monitoring:

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

For Windows PowerShell:

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

Usage

Starting the Server

# Start in local mode
uv run jvm-mcp-server

# Start with environment file (if remote connection is configured)
uv run --env-file .env jvm-mcp-server

# Start in a specific directory (if needed)
uv --directory /path/to/project run --env-file .env jvm-mcp-server

Using in Python Code

from jvm_mcp_server import JvmMcpServer

server = JvmMcpServer()
server.run()

Using with MCP Tools

With Configuration File

{
    "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"
        ]
      }
    }
}

Without Configuration File

This will read system environment variables. If none are present, it will monitor local threads:

{
    "mcpServers": {
      "jvm-mcp-server": {
        "command": "uv",
        "args": [
          "--directory",
          "/path/to/jvm-mcp-server",
          "run",
          "jvm-mcp-server"
        ]
      }
    }
}

Features

Automatic download and management of Arthas tools
Support for local and remote Java process monitoring
Java process list querying
Real-time JVM thread information
JVM memory usage monitoring
Thread stack trace information
Class loading information querying
Support for class and method decompilation
Method call monitoring
Dynamic log level adjustment
AI-driven JVM performance analysis

Important Notes

Ensure Java is installed in the runtime environment
Arthas tool will be automatically downloaded on first run (arthas will be downloaded to home directory, can be downloaded in advance and named as arthas-boot.jar)
Requires access permissions to target Java process
Remote mode requires SSH access and appropriate user permissions
Recommended for use in development environment, production use should be carefully evaluated

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "jvm-mcp-server" '{"command":"uv","args":["--directory","/path/to/jvm-mcp-server","run","jvm-mcp-server"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "jvm-mcp-server": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/jvm-mcp-server",
                "run",
                "jvm-mcp-server"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "jvm-mcp-server": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/jvm-mcp-server",
                "run",
                "jvm-mcp-server"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect