{"id":28918315,"url":"https://github.com/itz4blitz/jmx-mcp","last_synced_at":"2025-06-28T11:02:08.873Z","repository":{"id":300438540,"uuid":"1006152951","full_name":"itz4blitz/JMX-MCP","owner":"itz4blitz","description":"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.","archived":false,"fork":false,"pushed_at":"2025-06-21T17:06:55.000Z","size":9851,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-21T18:22:46.228Z","etag":null,"topics":["ai-assistant","claude-desktop","java","java-management","jmx","mbeans","mcp","model-context-protocol","model-context-protocol-servers","monitoring","spring-boot"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itz4blitz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-21T16:01:15.000Z","updated_at":"2025-06-21T17:36:15.000Z","dependencies_parsed_at":"2025-06-21T18:33:08.323Z","dependency_job_id":null,"html_url":"https://github.com/itz4blitz/JMX-MCP","commit_stats":null,"previous_names":["itz4blitz/jmx-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/itz4blitz/JMX-MCP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itz4blitz%2FJMX-MCP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itz4blitz%2FJMX-MCP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itz4blitz%2FJMX-MCP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itz4blitz%2FJMX-MCP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itz4blitz","download_url":"https://codeload.github.com/itz4blitz/JMX-MCP/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itz4blitz%2FJMX-MCP/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261224290,"owners_count":23126930,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assistant","claude-desktop","java","java-management","jmx","mbeans","mcp","model-context-protocol","model-context-protocol-servers","monitoring","spring-boot"],"created_at":"2025-06-22T02:02:38.417Z","updated_at":"2025-06-24T04:02:23.808Z","avatar_url":"https://github.com/itz4blitz.png","language":"Java","funding_links":[],"categories":["Monitoring"],"sub_categories":["How to Submit"],"readme":"# JMX MCP Server\n\n[![Java](https://img.shields.io/badge/Java-17+-orange.svg)](https://openjdk.java.net/)\n[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.4.1-brightgreen.svg)](https://spring.io/projects/spring-boot)\n[![MCP](https://img.shields.io/badge/MCP-2024--11--05-blue.svg)](https://modelcontextprotocol.io/)\n[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nA 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.\n\n## 🎥 Demo Video\n\nWatch the JMX MCP Server in action! See how Claude Desktop can monitor and manage Java applications through natural language:\n\nhttps://github.com/user-attachments/assets/722e1885-5aeb-4584-8116-b93324e0abc1\n\n*The demo shows real-time JMX monitoring, MBean exploration, and AI-powered Java application management through Claude Desktop.*\n\n## 🚀 Features\n\n### 🔍 **Comprehensive JMX Integration**\n- **Real-time MBean Discovery**: Automatically discovers and catalogs all available MBeans\n- **Attribute Management**: Read and write MBean attributes with full type safety\n- **Operation Execution**: Execute MBean operations with parameter validation\n- **Domain Exploration**: Browse and filter MBeans by domain\n\n### 🤖 **AI-Powered Monitoring**\n- **Natural Language Queries**: Ask questions like \"What's the current heap memory usage?\"\n- **Intelligent Analysis**: AI can correlate metrics and identify performance issues\n- **Automated Insights**: Get recommendations based on JMX data patterns\n\n### 🛡️ **Enterprise-Ready**\n- **Security Validation**: Built-in security controls and access validation\n- **Connection Management**: Robust local and remote JMX connection handling\n- **Error Handling**: Comprehensive error handling and recovery mechanisms\n- **Production Logging**: Configurable logging for different environments\n\n### 🔌 **MCP Protocol Compliance**\n- **Tools**: 12 JMX management tools for AI interaction\n- **Resources**: All JMX attributes exposed as discoverable resources\n- **STDIO Transport**: Optimized for Claude Desktop integration\n- **JSON-RPC 2.0**: Full protocol compliance for reliable communication\n\n## 📋 Prerequisites\n\n- **Java 17+** (OpenJDK or Oracle JDK)\n- **Maven 3.6+** for building\n- **Claude Desktop** or any MCP-compatible AI client\n\n## 🛠️ Quick Start\n\n### 1. Clone and Build\n\n```bash\ngit clone https://github.com/itz4blitz/JMX-MCP.git\ncd JMX-MCP\nmvn clean package\n```\n\n### 2. Test the Server\n\n```bash\n# Test with comprehensive validation\npython3 comprehensive-test.py\n```\n\n### 3. Configure Claude Desktop\n\nAdd to your Claude Desktop MCP configuration file:\n\n**Location:**\n- **macOS**: `~/.config/claude/mcp_servers.json`\n- **Windows**: `%APPDATA%\\Claude\\mcp_servers.json`\n\n**Configuration:**\n```json\n{\n  \"mcpServers\": {\n    \"jmx-mcp-server\": {\n      \"command\": \"java\",\n      \"args\": [\n        \"-Xmx512m\",\n        \"-Xms256m\",\n        \"-Dspring.profiles.active=stdio\",\n        \"-Dspring.main.banner-mode=off\",\n        \"-Dlogging.level.root=OFF\",\n        \"-Dspring.main.log-startup-info=false\",\n        \"-jar\",\n        \"/path/to/your/jmx-mcp-server-1.0.0.jar\"\n      ],\n      \"env\": {\n        \"JAVA_OPTS\": \"-Djava.awt.headless=true\"\n      }\n    }\n  }\n}\n```\n\n### 4. Start Using with Claude\n\nRestart Claude Desktop and try these queries:\n\n```\n\"What JMX tools are available?\"\n\"Show me the current heap memory usage\"\n\"List all MBean domains\"\n\"What's the garbage collection performance?\"\n```\n\n## 🔧 Available Tools (12 Total)\n\n### Core JMX Operations\n| Tool | Description | Example Usage |\n|------|-------------|---------------|\n| `listMBeans` | List all discovered MBeans with optional domain filtering | \"Show me all memory-related MBeans\" |\n| `getMBeanInfo` | Get detailed information about a specific MBean | \"Tell me about the Runtime MBean\" |\n| `getAttribute` | Read the value of an MBean attribute | \"What's the current heap memory usage?\" |\n| `setAttribute` | Set the value of a writable MBean attribute | \"Set the log level to DEBUG\" |\n| `listDomains` | List all available MBean domains | \"What domains are available?\" |\n\n### Connection Management\n| Tool | Description | Example Usage |\n|------|-------------|---------------|\n| `listJmxConnections` | List all configured JMX connections | \"Show me all available connections\" |\n| `addJmxConnection` | Add a new JMX connection | \"Connect to the production server\" |\n| `removeJmxConnection` | Remove a JMX connection | \"Remove the old test connection\" |\n| `switchJmxConnection` | Switch to a different JMX connection | \"Switch to the staging environment\" |\n| `getConnectionInfo` | Get current JMX connection status and statistics | \"Is the JMX connection healthy?\" |\n\n### Service Discovery\n| Tool | Description | Example Usage |\n|------|-------------|---------------|\n| `discoverJmxServices` | Discover JMX-enabled Java applications on the system | \"Find all Java apps with JMX enabled\" |\n| `autoRegisterDiscoveredConnections` | Automatically register discovered JMX services | \"Auto-connect to all discovered Java apps\" |\n\n## 📊 Available Resources\n\nThe server automatically exposes **all JMX attributes** as MCP resources, making them discoverable and accessible to AI assistants:\n\n- **Memory Metrics**: Heap usage, non-heap usage, memory pools\n- **Garbage Collection**: GC statistics, collection times, collection counts\n- **Threading**: Thread counts, deadlock detection, thread states\n- **Runtime Information**: JVM uptime, start time, system properties\n- **Class Loading**: Loaded classes, unloaded classes, class path\n- **Operating System**: CPU usage, system load, available processors\n\n**Resource URI Format:**\n```\njmx://domain:type=Type,name=Name/attributes/AttributeName\n```\n\n**Example Resources:**\n```\njmx://java.lang:type=Memory/attributes/HeapMemoryUsage\njmx://java.lang:type=Runtime/attributes/Uptime\njmx://java.lang:type=GarbageCollector,name=G1_Young_Generation/attributes/CollectionCount\n```\n\n## 💬 Example Interactions\n\n### Memory Monitoring\n```\nUser: \"What's the current memory situation?\"\nClaude: I'll check the JMX memory metrics for you.\n\n[Uses getAttribute tool to read HeapMemoryUsage]\n\nThe current heap memory usage is:\n- Used: 245 MB\n- Committed: 512 MB  \n- Max: 2048 MB\n- Usage: 12% of maximum heap\n\nThe application is running efficiently with low memory pressure.\n```\n\n### Performance Analysis\n```\nUser: \"Are there any performance issues?\"\nClaude: Let me analyze the JMX performance metrics.\n\n[Uses multiple tools to check GC, threads, and memory]\n\nPerformance analysis:\n✅ Memory: Healthy (12% heap usage)\n✅ GC: Efficient (avg 15ms collection time)\n⚠️  Threads: High count (245 threads) - consider investigation\n✅ CPU: Normal load\n\nRecommendation: Monitor thread creation patterns.\n```\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   Claude AI     │◄──►│  JMX MCP Server  │◄──►│  Java App JMX   │\n│                 │    │                  │    │                 │\n│ Natural Language│    │ • Tools (12)     │    │ • MBeans        │\n│ Queries         │    │ • Resources(224+)│    │ • Attributes    │\n│                 │    │ • JSON-RPC 2.0   │    │ • Operations    │\n│                 │    │ • Multi-Connect  │    │ • Discovery     │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n```\n\n### Core Components\n\n- **JMXConnectionManager**: Manages local and remote JMX connections\n- **MBeanDiscoveryService**: Discovers and catalogs available MBeans\n- **JmxService**: Provides @Tool-annotated methods for AI interaction\n- **JMXToMCPMapper**: Maps JMX attributes to MCP resources\n- **JmxSecurityValidator**: Validates operations for security compliance\n\n## ⚙️ Configuration Profiles\n\n### Default Profile\nStandard configuration with full logging for development and debugging.\n\n### STDIO Profile\nOptimized for Claude Desktop integration:\n- **Silent Operation**: No console output to avoid JSON-RPC interference\n- **Minimal Logging**: Error-only logging to prevent file system issues\n- **Fast Startup**: Optimized initialization for quick AI responses\n\n## 🧪 Testing\n\n### Comprehensive Test Suite\n```bash\n# Run the comprehensive integration test\npython3 comprehensive-test.py\n```\n\n**Test Coverage:**\n- ✅ MCP Protocol compliance\n- ✅ JSON-RPC 2.0 communication\n- ✅ All 12 tools registration and execution\n- ✅ Multi-connection management\n- ✅ Service discovery and auto-registration\n- ✅ Resource discovery and access\n- ✅ Error handling and recovery\n\n### Unit Tests\n```bash\nmvn test\n```\n\n## 🔒 Security\n\n### Built-in Security Features\n- **ObjectName Validation**: Prevents access to sensitive MBeans\n- **Operation Filtering**: Restricts dangerous operations\n- **Type Safety**: Validates attribute types before operations\n- **Access Control**: Configurable security policies\n\n### Security Configuration\n```yaml\njmx:\n  security:\n    enabled: true\n    allowed-domains:\n      - \"java.lang\"\n      - \"java.nio\"\n      - \"com.myapp\"\n    blocked-operations:\n      - \"shutdown\"\n      - \"restart\"\n```\n\n## 🚀 Deployment\n\n### Local Development\n```bash\njava -jar target/jmx-mcp-server-1.0.0.jar\n```\n\n### Production Deployment\n```bash\njava -Xmx1g -Xms512m \\\n     -Dspring.profiles.active=production \\\n     -jar jmx-mcp-server-1.0.0.jar\n```\n\n### Docker Deployment\n```dockerfile\nFROM openjdk:17-jre-slim\nCOPY target/jmx-mcp-server-1.0.0.jar app.jar\nEXPOSE 8080\nENTRYPOINT [\"java\", \"-jar\", \"/app.jar\"]\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass\n6. Submit a pull request\n\n### Code Style\n- Follow Java coding conventions\n- Use meaningful variable and method names\n- Add comprehensive JavaDoc comments\n- Maintain test coverage above 80%\n\n## 📚 Documentation\n\n- **[API Documentation](docs/API.md)**: Detailed API reference\n- **[Configuration Guide](docs/CONFIGURATION.md)**: Advanced configuration options\n- **[Troubleshooting](docs/TROUBLESHOOTING.md)**: Common issues and solutions\n- **[Examples](examples/)**: Usage examples and tutorials\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**Server won't start with Claude Desktop:**\n- Verify Java 17+ is installed\n- Check the JAR path in configuration\n- Ensure STDIO profile is active\n\n**No tools/resources visible:**\n- Restart Claude Desktop after configuration changes\n- Check server logs for errors\n- Verify MCP protocol compliance\n\n**Connection issues:**\n- Confirm JMX is enabled on target application\n- Check network connectivity for remote connections\n- Validate security settings\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Quick Start for Contributors\n\n```bash\n# Fork the repository on GitHub\ngit clone https://github.com/YOUR_USERNAME/JMX-MCP.git\ncd JMX-MCP\n\n# Build and test\nmvn clean compile\nmvn test\n\n# Run the application\nmvn spring-boot:run\n```\n\n### Ways to Contribute\n\n- 🐛 **Report bugs** - Help us identify and fix issues\n- 💡 **Suggest features** - Share ideas for new functionality\n- 📝 **Improve documentation** - Help others understand the project\n- 🔧 **Submit code** - Fix bugs or implement new features\n- 🧪 **Write tests** - Improve test coverage and reliability\n- 🎨 **UI/UX improvements** - Enhance user experience\n\n### Community\n\n- **GitHub Discussions**: Ask questions and share ideas\n- **Issues**: Report bugs and request features\n- **Pull Requests**: Contribute code improvements\n- **Wiki**: Collaborative documentation\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **Spring AI Team** for the excellent MCP framework\n- **Model Context Protocol** for the standardized AI integration protocol\n- **Anthropic** for Claude Desktop and AI assistant capabilities\n- **OpenJDK Community** for the robust Java platform\n\n## 📞 Support\n\n- **Issues**: [GitHub Issues](https://github.com/itz4blitz/JMX-MCP/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/itz4blitz/JMX-MCP/discussions)\n- **Documentation**: [Wiki](https://github.com/itz4blitz/JMX-MCP/wiki)\n\n---\n\n**Made with ❤️ for the AI and Java communities**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitz4blitz%2Fjmx-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitz4blitz%2Fjmx-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitz4blitz%2Fjmx-mcp/lists"}