# JVM MCP Server

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.6+-blue.svg" alt="Python Version">
  <img src="https://img.shields.io/badge/JDK-8+-green.svg" alt="JDK Version">
  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License">
</p>

[English](README.md) | [中文](README_zh.md)

[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/xzq-xu-jvm-mcp-server-badge.png)](https://mseep.ai/app/xzq-xu-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.

<a href="https://glama.ai/mcp/servers/@xzq-xu/jvm-mcp-server">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@xzq-xu/jvm-mcp-server/badge" alt="JVM Server MCP server" />
</a>

## Hosted deployment

A hosted deployment is available on [Fronteir AI](https://fronteir.ai/mcp/xzq-xu-jvm-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)

```bash
# 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

```bash
pip install jvm-mcp-server
```

### From Source

```bash
# 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)

```bash
# 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

```bash
# Local mode
uvx run jvm-mcp-server

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

#### Using Python directly

```python
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

```json
{
  "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](./doc/available_tools.md).

## 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](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](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