JVM MCP Server

1# JVM MCP Server
2 
3<p align="center">
4  <img src="https://img.shields.io/badge/Python-3.6+-blue.svg" alt="Python Version">
5  <img src="https://img.shields.io/badge/JDK-8+-green.svg" alt="JDK Version">
6  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License">
7</p>
8 
9[English](README.md) | [中文](README_zh.md)
10 
11[![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)
12 
13 
14A 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.
15 
16<a href="https://glama.ai/mcp/servers/@xzq-xu/jvm-mcp-server">
17  <img width="380" height="200" src="https://glama.ai/mcp/servers/@xzq-xu/jvm-mcp-server/badge" alt="JVM Server MCP server" />
18</a>
19 
20## Features
21 
22- **Zero Dependencies**: Uses only native JDK tools (jps, jstack, jmap, etc.)
23- **Lightweight**: Minimal resource consumption compared to agent-based solutions
24- **High Compatibility**: Works with all Java versions and platforms
25- **Non-Intrusive**: No modifications to target applications required
26- **Secure**: Uses only JDK certified tools and commands
27- **Remote Monitoring**: Support for both local and remote JVM monitoring via SSH
28 
29## Core Capabilities
30 
31### Basic Monitoring
32- Java process listing and identification
33- JVM basic information retrieval
34- Memory usage monitoring
35- Thread information and stack trace analysis
36- Class loading statistics
37- Detailed class structure information
38 
39### Advanced Features
40- Method call path analysis
41- Class decompilation
42- Method search and inspection
43- Method invocation monitoring
44- Logger level management
45- System resource dashboard
46 
47## System Requirements
48 
49- Python 3.6+
50- JDK 8+
51- Linux/Unix/Windows OS
52- SSH access (for remote monitoring)
53 
54## Installation
55 
56### Using uv (Recommended)
57 
58```bash
59# Install uv if not already installed
60curl -LsSf https://astral.sh/uv/install.sh | sh  # Linux/macOS
61# or
62powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows
63 
64# Install the package
65uv pip install jvm-mcp-server
66```
67 
68### Using pip
69 
70```bash
71pip install jvm-mcp-server
72```
73 
74### From Source
75 
76```bash
77# Clone the repository
78git clone https://github.com/your-repo/jvm-mcp-server.git
79cd jvm-mcp-server
80 
81# Using uv (recommended)
82uv venv  # Create virtual environment
83uv sync  # Install dependencies
84 
85# Or install in development mode
86uv pip install -e .
87```
88 
89## Quick Start
90 
91### Starting the Server
92 
93#### Using uv (Recommended)
94 
95```bash
96# Local mode
97uv run jvm-mcp-server
98 
99# Using environment variables file for remote mode
100uv run --env-file .env jvm-mcp-server
101 
102# In specific directory
103uv --directory /path/to/project run --env-file .env jvm-mcp-server
104```
105 
106#### Using uvx
107 
108```bash
109# Local mode
110uvx run jvm-mcp-server
111 
112# With environment variables
113uvx run --env-file .env jvm-mcp-server
114```
115 
116#### Using Python directly
117 
118```python
119from jvm_mcp_server import JvmMcpServer
120 
121# Local mode
122server = JvmMcpServer()
123server.run()
124 
125# Remote mode (via environment variables)
126# Set SSH_HOST, SSH_PORT, SSH_USER, SSH_PASSWORD or SSH_KEY
127import os
128os.environ['SSH_HOST'] = 'user@remote-host'
129os.environ['SSH_PORT'] = '22'
130server = JvmMcpServer()
131server.run()
132```
133 
134### Using with MCP Configuration
135 
136```json
137{
138  "mcpServers": {
139    "jvm-mcp-server": {
140      "command": "uv",
141      "args": [
142        "--directory",
143        "/path/to/jvm-mcp-server",
144        "run",
145        "--env-file",
146        "/path/to/jvm-mcp-server/.env",
147        "jvm-mcp-server"
148      ]
149    }
150  }
151}
152```
153 
154## Available Tools
155 
156JVM-MCP-Server provides a comprehensive set of tools for JVM monitoring and diagnostics:
157 
158- `list_java_processes`: List all Java processes
159- `get_thread_info`: Get thread information for a specific process
160- `get_jvm_info`: Get JVM basic information
161- `get_memory_info`: Get memory usage information
162- `get_stack_trace`: Get thread stack trace information
163- `get_class_info`: Get detailed class information including structure
164- `get_stack_trace_by_method`: Get method call path
165- `decompile_class`: Decompile class source code
166- `search_method`: Search for methods in classes
167- `watch_method`: Monitor method invocations
168- `get_logger_info`: Get logger information
169- `set_logger_level`: Set logger levels
170- `get_dashboard`: Get system resource dashboard
171- `get_jcmd_output`: Execute JDK jcmd commands
172- `get_jstat_output`: Execute JDK jstat commands
173 
174For detailed documentation on each tool, see [Available Tools](./doc/available_tools.md).
175 
176## Architecture
177 
178JVM-MCP-Server is built on a modular architecture:
179 
1801. **Command Layer**: Wraps JDK native commands
1812. **Executor Layer**: Handles local and remote command execution
1823. **Formatter Layer**: Processes and formats command output
1834. **MCP Interface**: Exposes functionality through FastMCP protocol
184 
185### Key Components
186 
187- `BaseCommand`: Abstract base class for all commands
188- `CommandExecutor`: Interface for command execution (local and remote)
189- `OutputFormatter`: Interface for formatting command output
190- `JvmMcpServer`: Main server class that registers all tools
191 
192## Development Status
193 
194The project is in active development. See [Native_TODO.md](Native_TODO.md) for current progress.
195 
196### Completed
197- Core architecture and command framework
198- Basic commands implementation (jps, jstack, jmap, jinfo, jcmd, jstat)
199- Class information retrieval system
200- MCP tool parameter type compatibility fixes
201 
202### In Progress
203- Caching mechanism
204- Method tracing
205- Performance monitoring
206- Error handling improvements
207 
208## Contributing
209 
210Contributions are welcome! Please feel free to submit a Pull Request.
211 
2121. Fork the repository
2132. Create your feature branch (`git checkout -b feature/amazing-feature`)
2143. Commit your changes (`git commit -m 'Add some amazing feature'`)
2154. Push to the branch (`git push origin feature/amazing-feature`)
2165. Open a Pull Request
217 
218## License
219 
220This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
221 
222## Acknowledgements
223 
224- JDK tools documentation
225- FastMCP protocol specification
226- Contributors and testers 
227