A powerful Model Context Protocol (MCP) server that provides comprehensive JMX monitoring and management capabilities for AI assistants like Claude Desktop. Monitor Java applications, manage MBeans, and perform JMX operations through natural language interactions.
Watch the JMX MCP Server in action! See how Claude Desktop can monitor and manage Java applications through natural language:
JMX-MCP.mp4
The demo shows real-time JMX monitoring, MBean exploration, and AI-powered Java application management through Claude Desktop.
- Real-time MBean Discovery: Automatically discovers and catalogs all available MBeans
- Attribute Management: Read and write MBean attributes with full type safety
- Operation Execution: Execute MBean operations with parameter validation
- Domain Exploration: Browse and filter MBeans by domain
- Natural Language Queries: Ask questions like "What's the current heap memory usage?"
- Intelligent Analysis: AI can correlate metrics and identify performance issues
- Automated Insights: Get recommendations based on JMX data patterns
- Security Validation: Built-in security controls and access validation
- Connection Management: Robust local and remote JMX connection handling
- Error Handling: Comprehensive error handling and recovery mechanisms
- Production Logging: Configurable logging for different environments
- Tools: 12 JMX management tools for AI interaction
- Resources: All JMX attributes exposed as discoverable resources
- STDIO Transport: Optimized for Claude Desktop integration
- JSON-RPC 2.0: Full protocol compliance for reliable communication
- Java 17+ (OpenJDK or Oracle JDK)
- Maven 3.6+ for building
- Claude Desktop or any MCP-compatible AI client
git clone https://github.com/itz4blitz/JMX-MCP.git
cd JMX-MCP
mvn clean package# Test with comprehensive validation
python3 comprehensive-test.pyAdd to your Claude Desktop MCP configuration file:
Location:
- macOS:
~/.config/claude/mcp_servers.json - Windows:
%APPDATA%\Claude\mcp_servers.json
Configuration:
{
"mcpServers": {
"jmx-mcp-server": {
"command": "java",
"args": [
"-Xmx512m",
"-Xms256m",
"-Dspring.profiles.active=stdio",
"-Dspring.main.banner-mode=off",
"-Dlogging.level.root=OFF",
"-Dspring.main.log-startup-info=false",
"-jar",
"/path/to/your/jmx-mcp-server-1.0.0.jar"
],
"env": {
"JAVA_OPTS": "-Djava.awt.headless=true"
}
}
}
}Restart Claude Desktop and try these queries:
"What JMX tools are available?"
"Show me the current heap memory usage"
"List all MBean domains"
"What's the garbage collection performance?"
| Tool | Description | Example Usage |
|---|---|---|
listMBeans |
List all discovered MBeans with optional domain filtering | "Show me all memory-related MBeans" |
getMBeanInfo |
Get detailed information about a specific MBean | "Tell me about the Runtime MBean" |
getAttribute |
Read the value of an MBean attribute | "What's the current heap memory usage?" |
setAttribute |
Set the value of a writable MBean attribute | "Set the log level to DEBUG" |
listDomains |
List all available MBean domains | "What domains are available?" |
| Tool | Description | Example Usage |
|---|---|---|
listJmxConnections |
List all configured JMX connections | "Show me all available connections" |
addJmxConnection |
Add a new JMX connection | "Connect to the production server" |
removeJmxConnection |
Remove a JMX connection | "Remove the old test connection" |
switchJmxConnection |
Switch to a different JMX connection | "Switch to the staging environment" |
getConnectionInfo |
Get current JMX connection status and statistics | "Is the JMX connection healthy?" |
| Tool | Description | Example Usage |
|---|---|---|
discoverJmxServices |
Discover JMX-enabled Java applications on the system | "Find all Java apps with JMX enabled" |
autoRegisterDiscoveredConnections |
Automatically register discovered JMX services | "Auto-connect to all discovered Java apps" |
The server automatically exposes all JMX attributes as MCP resources, making them discoverable and accessible to AI assistants:
- Memory Metrics: Heap usage, non-heap usage, memory pools
- Garbage Collection: GC statistics, collection times, collection counts
- Threading: Thread counts, deadlock detection, thread states
- Runtime Information: JVM uptime, start time, system properties
- Class Loading: Loaded classes, unloaded classes, class path
- Operating System: CPU usage, system load, available processors
Resource URI Format:
jmx://domain:type=Type,name=Name/attributes/AttributeName
Example Resources:
jmx://java.lang:type=Memory/attributes/HeapMemoryUsage
jmx://java.lang:type=Runtime/attributes/Uptime
jmx://java.lang:type=GarbageCollector,name=G1_Young_Generation/attributes/CollectionCount
User: "What's the current memory situation?"
Claude: I'll check the JMX memory metrics for you.
[Uses getAttribute tool to read HeapMemoryUsage]
The current heap memory usage is:
- Used: 245 MB
- Committed: 512 MB
- Max: 2048 MB
- Usage: 12% of maximum heap
The application is running efficiently with low memory pressure.
User: "Are there any performance issues?"
Claude: Let me analyze the JMX performance metrics.
[Uses multiple tools to check GC, threads, and memory]
Performance analysis:
✅ Memory: Healthy (12% heap usage)
✅ GC: Efficient (avg 15ms collection time)
⚠️ Threads: High count (245 threads) - consider investigation
✅ CPU: Normal load
Recommendation: Monitor thread creation patterns.
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Claude AI │◄──►│ JMX MCP Server │◄──►│ Java App JMX │
│ │ │ │ │ │
│ Natural Language│ │ • Tools (12) │ │ • MBeans │
│ Queries │ │ • Resources(224+)│ │ • Attributes │
│ │ │ • JSON-RPC 2.0 │ │ • Operations │
│ │ │ • Multi-Connect │ │ • Discovery │
└─────────────────┘ └──────────────────┘ └─────────────────┘
- JMXConnectionManager: Manages local and remote JMX connections
- MBeanDiscoveryService: Discovers and catalogs available MBeans
- JmxService: Provides @Tool-annotated methods for AI interaction
- JMXToMCPMapper: Maps JMX attributes to MCP resources
- JmxSecurityValidator: Validates operations for security compliance
Standard configuration with full logging for development and debugging.
Optimized for Claude Desktop integration:
- Silent Operation: No console output to avoid JSON-RPC interference
- Minimal Logging: Error-only logging to prevent file system issues
- Fast Startup: Optimized initialization for quick AI responses
# Run the comprehensive integration test
python3 comprehensive-test.pyTest Coverage:
- ✅ MCP Protocol compliance
- ✅ JSON-RPC 2.0 communication
- ✅ All 12 tools registration and execution
- ✅ Multi-connection management
- ✅ Service discovery and auto-registration
- ✅ Resource discovery and access
- ✅ Error handling and recovery
mvn test- ObjectName Validation: Prevents access to sensitive MBeans
- Operation Filtering: Restricts dangerous operations
- Type Safety: Validates attribute types before operations
- Access Control: Configurable security policies
jmx:
security:
enabled: true
allowed-domains:
- "java.lang"
- "java.nio"
- "com.myapp"
blocked-operations:
- "shutdown"
- "restart"java -jar target/jmx-mcp-server-1.0.0.jarjava -Xmx1g -Xms512m \
-Dspring.profiles.active=production \
-jar jmx-mcp-server-1.0.0.jarFROM openjdk:17-jre-slim
COPY target/jmx-mcp-server-1.0.0.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
- Follow Java coding conventions
- Use meaningful variable and method names
- Add comprehensive JavaDoc comments
- Maintain test coverage above 80%
- API Documentation: Detailed API reference
- Configuration Guide: Advanced configuration options
- Troubleshooting: Common issues and solutions
- Examples: Usage examples and tutorials
Server won't start with Claude Desktop:
- Verify Java 17+ is installed
- Check the JAR path in configuration
- Ensure STDIO profile is active
No tools/resources visible:
- Restart Claude Desktop after configuration changes
- Check server logs for errors
- Verify MCP protocol compliance
Connection issues:
- Confirm JMX is enabled on target application
- Check network connectivity for remote connections
- Validate security settings
We welcome contributions! Please see our Contributing Guide for details.
# Fork the repository on GitHub
git clone https://github.com/YOUR_USERNAME/JMX-MCP.git
cd JMX-MCP
# Build and test
mvn clean compile
mvn test
# Run the application
mvn spring-boot:run- 🐛 Report bugs - Help us identify and fix issues
- 💡 Suggest features - Share ideas for new functionality
- 📝 Improve documentation - Help others understand the project
- 🔧 Submit code - Fix bugs or implement new features
- 🧪 Write tests - Improve test coverage and reliability
- 🎨 UI/UX improvements - Enhance user experience
- GitHub Discussions: Ask questions and share ideas
- Issues: Report bugs and request features
- Pull Requests: Contribute code improvements
- Wiki: Collaborative documentation
This project is licensed under the MIT License - see the LICENSE file for details.
- Spring AI Team for the excellent MCP framework
- Model Context Protocol for the standardized AI integration protocol
- Anthropic for Claude Desktop and AI assistant capabilities
- OpenJDK Community for the robust Java platform
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: Wiki
Made with ❤️ for the AI and Java communities