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

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