JVM MCP Server

English | 中文

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.

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

Related MCP server: MCP System Info Server

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-server

Using pip

pip install jvm-mcp-server

From 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-server

Using uvx

# Local mode
uvx run jvm-mcp-server

# With environment variables
uvx run --env-file .env jvm-mcp-server

Using 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 processes

• get_thread_info: Get thread information for a specific process

• get_jvm_info: Get JVM basic information

• get_memory_info: Get memory usage information

• get_stack_trace: Get thread stack trace information

• get_class_info: Get detailed class information including structure

• get_stack_trace_by_method: Get method call path

• decompile_class: Decompile class source code

• search_method: Search for methods in classes

• watch_method: Monitor method invocations

• get_logger_info: Get logger information

• set_logger_level: Set logger levels

• get_dashboard: Get system resource dashboard

• get_jcmd_output: Execute JDK jcmd commands

• get_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:

1. Command Layer: Wraps JDK native commands

2. Executor Layer: Handles local and remote command execution

3. Formatter Layer: Processes and formats command output

4. MCP Interface: Exposes functionality through FastMCP protocol

Key Components

• BaseCommand: Abstract base class for all commands

• CommandExecutor: Interface for command execution (local and remote)

• OutputFormatter: Interface for formatting command output

• JvmMcpServer: 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.

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add some amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. 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