JMX MCP Server

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.

🎥 Demo Video

Watch the JMX MCP Server in action! See how Claude Desktop can monitor and manage Java applications through natural language:

https://github.com/user-attachments/assets/722e1885-5aeb-4584-8116-b93324e0abc1

*The demo shows real-time JMX monitoring, MBean exploration, and AI-powered Java application management through Claude Desktop.*

🚀 Features

🔍 Comprehensive JMX Integration

• 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

🤖 AI-Powered Monitoring

• 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

🛡️ Enterprise-Ready

• 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

🔌 MCP Protocol Compliance

• 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

📋 Prerequisites

• Java 17+ (OpenJDK or Oracle JDK)
• Maven 3.6+ for building
• Claude Desktop or any MCP-compatible AI client

🛠️ Quick Start

1. Clone and Build

git clone https://github.com/itz4blitz/JMX-MCP.git
cd JMX-MCP
mvn clean package

2. Test the Server

# Test with comprehensive validation
python3 comprehensive-test.py

3. Configure Claude Desktop

Add 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"
      }
    }
  }
}

4. Start Using with Claude

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?"

🔧 Available Tools (12 Total)

Core JMX Operations

Connection Management

Service Discovery

📊 Available Resources

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

💬 Example Interactions

Memory Monitoring

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.

Performance Analysis

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.

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   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     │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Core Components

• 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

⚙️ Configuration Profiles

Default Profile

Standard configuration with full logging for development and debugging.

STDIO Profile

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

🧪 Testing

Comprehensive Test Suite

# Run the comprehensive integration test
python3 comprehensive-test.py

Test 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

Unit Tests

mvn test

🔒 Security

Built-in Security Features

• ObjectName Validation: Prevents access to sensitive MBeans
• Operation Filtering: Restricts dangerous operations
• Type Safety: Validates attribute types before operations
• Access Control: Configurable security policies

Security Configuration

jmx:
  security:
    enabled: true
    allowed-domains:
      - "java.lang"
      - "java.nio"
      - "com.myapp"
    blocked-operations:
      - "shutdown"
      - "restart"

🚀 Deployment

Local Development

java -jar target/jmx-mcp-server-1.0.0.jar

Production Deployment

java -Xmx1g -Xms512m \
     -Dspring.profiles.active=production \
     -jar jmx-mcp-server-1.0.0.jar

Docker Deployment

FROM openjdk:17-jre-slim
COPY target/jmx-mcp-server-1.0.0.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests for new functionality

5. Ensure all tests pass

6. Submit a pull request

Code Style

• Follow Java coding conventions
• Use meaningful variable and method names
• Add comprehensive JavaDoc comments
• Maintain test coverage above 80%

📚 Documentation

• **API Documentation**: Detailed API reference
• **Configuration Guide**: Advanced configuration options
• **Troubleshooting**: Common issues and solutions
• **Examples**: Usage examples and tutorials

🐛 Troubleshooting

Common Issues

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

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Start for Contributors

# 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

Ways to Contribute

• 🐛 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

Community

• GitHub Discussions: Ask questions and share ideas
• Issues: Report bugs and request features
• Pull Requests: Contribute code improvements
• Wiki: Collaborative documentation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• 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

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

Made with ❤️ for the AI and Java communities