Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/itz4blitz/jmx-mcp

A powerful Model Context Protocol (MCP) server that enables AI assistants like Claude Desktop to monitor and manage Java applications through JMX. Provides real-time MBean discovery, attribute management, and natural language JMX operations.
https://github.com/itz4blitz/jmx-mcp

ai-assistant claude-desktop java java-management jmx mbeans mcp model-context-protocol model-context-protocol-servers monitoring spring-boot

Last synced: 3 months ago
JSON representation

A powerful Model Context Protocol (MCP) server that enables AI assistants like Claude Desktop to monitor and manage Java applications through JMX. Provides real-time MBean discovery, attribute management, and natural language JMX operations.

Awesome Lists containing this project

README 

          
# JMX MCP Server



[![Java](https://img.shields.io/badge/Java-17+-orange.svg)](https://openjdk.java.net/)

[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.4.1-brightgreen.svg)](https://spring.io/projects/spring-boot)

[![MCP](https://img.shields.io/badge/MCP-2024--11--05-blue.svg)](https://modelcontextprotocol.io/)

[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)



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



```bash

git clone https://github.com/itz4blitz/JMX-MCP.git

cd JMX-MCP

mvn clean package

```



### 2. Test the Server



```bash

# 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:**

```json

{

  "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

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



### Connection Management

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



### Service Discovery

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



## 📊 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

```bash

# 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

```bash

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

```yaml

jmx:

  security:

    enabled: true

    allowed-domains:

      - "java.lang"

      - "java.nio"

      - "com.myapp"

    blocked-operations:

      - "shutdown"

      - "restart"

```



## 🚀 Deployment



### Local Development

```bash

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

```



### Production Deployment

```bash

java -Xmx1g -Xms512m \

     -Dspring.profiles.active=production \

     -jar jmx-mcp-server-1.0.0.jar

```



### Docker Deployment

```dockerfile

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](CONTRIBUTING.md) 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](docs/API.md)**: Detailed API reference

- **[Configuration Guide](docs/CONFIGURATION.md)**: Advanced configuration options

- **[Troubleshooting](docs/TROUBLESHOOTING.md)**: Common issues and solutions

- **[Examples](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](CONTRIBUTING.md) for details.



### Quick Start for Contributors



```bash

# 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](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](https://github.com/itz4blitz/JMX-MCP/issues)

- **Discussions**: [GitHub Discussions](https://github.com/itz4blitz/JMX-MCP/discussions)

- **Documentation**: [Wiki](https://github.com/itz4blitz/JMX-MCP/wiki)



---



**Made with ❤️ for the AI and Java communities**