shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

jmx-mcp

一个强大的JMX MCP服务器，为Claude Desktop等AI助手提供全面的JMX监控和管理功能，支持通过自然语言交互监控Java应用、管理MBean和执行JMX操作。

article

README

🚀 JMX MCP 服务器

JMX MCP 服务器是一款强大的模型上下文协议（MCP）服务器，为像 Claude Desktop 这样的 AI 助手提供全面的 JMX 监控和管理功能。它允许用户通过自然语言交互来监控 Java 应用程序、管理 MBeans 并执行 JMX 操作。

🚀 快速开始

1. 克隆并构建项目

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

2. 测试服务器

# 使用综合验证进行测试
python3 comprehensive-test.py

3. 配置 Claude Desktop

将以下内容添加到你的 Claude Desktop MCP 配置文件中：

  • 位置：
    • macOS：~/.config/claude/mcp_servers.json
    • Windows：%APPDATA%\Claude\mcp_servers.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. 开始与 Claude 一起使用

重启 Claude Desktop 并尝试以下查询：

"What JMX tools are available?"
"Show me the current heap memory usage"
"List all MBean domains"
"What's the garbage collection performance?"

✨ 主要特性

🔍 全面的 JMX 集成

  • 实时 MBean 发现：自动发现并编目所有可用的 MBeans。
  • 属性管理：以完全类型安全的方式读取和写入 MBean 属性。
  • 操作执行：通过参数验证执行 MBean 操作。
  • 域探索：按域浏览和过滤 MBeans。

🤖 AI 驱动的监控

  • 自然语言查询：可以提出诸如“当前堆内存使用情况如何？”之类的问题。
  • 智能分析：AI 可以关联指标并识别性能问题。
  • 自动洞察：根据 JMX 数据模式提供建议。

🛡️ 企业级就绪

  • 安全验证：内置安全控制和访问验证。
  • 连接管理：强大的本地和远程 JMX 连接处理。
  • 错误处理：全面的错误处理和恢复机制。
  • 生产日志记录：可针对不同环境配置日志记录。

🔌 MCP 协议合规

  • 工具：提供 12 个用于 AI 交互的 JMX 管理工具。
  • 资源：所有 JMX 属性都作为可发现资源公开。
  • STDIO 传输：针对 Claude Desktop 集成进行了优化。
  • JSON-RPC 2.0：完全符合协议，确保可靠通信。

📦 安装指南

前提条件

  • Java 17+（OpenJDK 或 Oracle JDK）
  • Maven 3.6+ 用于构建项目
  • Claude Desktop 或任何与 MCP 兼容的 AI 客户端

💻 使用示例

基础用法

内存监控

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.

📚 详细文档

可用工具（共 12 个）

核心 JMX 操作

| 工具 | 描述 | 示例用法 | |------|-------------|---------------| | listMBeans | 列出所有发现的 MBeans，并可选择按域过滤 | "Show me all memory-related MBeans" | | getMBeanInfo | 获取特定 MBean 的详细信息 | "Tell me about the Runtime MBean" | | getAttribute | 读取 MBean 属性的值 | "What's the current heap memory usage?" | | setAttribute | 设置可写 MBean 属性的值 | "Set the log level to DEBUG" | | listDomains | 列出所有可用的 MBean 域 | "What domains are available?" |

连接管理

| 工具 | 描述 | 示例用法 | |------|-------------|---------------| | listJmxConnections | 列出所有配置的 JMX 连接 | "Show me all available connections" | | addJmxConnection | 添加新的 JMX 连接 | "Connect to the production server" | | removeJmxConnection | 删除 JMX 连接 | "Remove the old test connection" | | switchJmxConnection | 切换到不同的 JMX 连接 | "Switch to the staging environment" | | getConnectionInfo | 获取当前 JMX 连接的状态和统计信息 | "Is the JMX connection healthy?" |

服务发现

| 工具 | 描述 | 示例用法 | |------|-------------|---------------| | discoverJmxServices | 发现系统上启用 JMX 的 Java 应用程序 | "Find all Java apps with JMX enabled" | | autoRegisterDiscoveredConnections | 自动注册发现的 JMX 服务 | "Auto-connect to all discovered Java apps" |

可用资源

服务器自动将所有 JMX 属性作为 MCP 资源公开，使 AI 助手可以发现和访问这些资源：

  • 内存指标：堆使用情况、非堆使用情况、内存池。
  • 垃圾回收：GC 统计信息、收集时间、收集次数。
  • 线程：线程计数、死锁检测、线程状态。
  • 运行时信息：JVM 正常运行时间、启动时间、系统属性。
  • 类加载：已加载的类、卸载的类、类路径。
  • 操作系统：CPU 使用情况、系统负载、可用处理器。

资源 URI 格式：

jmx://domain:type=Type,name=Name/attributes/AttributeName

示例资源：

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

架构

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   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：管理本地和远程 JMX 连接。
  • MBeanDiscoveryService：发现并编目可用的 MBeans。
  • JmxService：提供带有 @Tool 注解的方法用于 AI 交互。
  • JMXToMCPMapper：将 JMX 属性映射到 MCP 资源。
  • JmxSecurityValidator：验证操作是否符合安全要求。

配置文件

默认配置文件

标准配置，具有完整的日志记录，适用于开发和调试。

STDIO 配置文件

针对 Claude Desktop 集成进行了优化：

  • 静默操作：无控制台输出，避免干扰 JSON-RPC。
  • 最小日志记录：仅记录错误信息，防止文件系统问题。
  • 快速启动：优化初始化过程，实现快速的 AI 响应。

🔧 技术细节

测试

综合测试套件

# 运行综合集成测试
python3 comprehensive-test.py

测试覆盖范围：

  • ✅ MCP 协议合规性
  • ✅ JSON-RPC 2.0 通信
  • ✅ 所有 12 个工具的注册和执行
  • ✅ 多连接管理
  • ✅ 服务发现和自动注册
  • ✅ 资源发现和访问
  • ✅ 错误处理和恢复

单元测试

mvn test

安全

内置安全功能

  • ObjectName 验证：防止访问敏感 MBeans。
  • 操作过滤：限制危险操作。
  • 类型安全：在操作前验证属性类型。
  • 访问控制：可配置的安全策略。

安全配置

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.jar

生产部署

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

Docker 部署

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

🤝 贡献代码

我们欢迎贡献！请查看我们的 贡献指南 以获取详细信息。

贡献者快速入门

# 在 GitHub 上 Fork 仓库
git clone https://github.com/YOUR_USERNAME/JMX-MCP.git
cd JMX-MCP

# 构建和测试
mvn clean compile
mvn test

# 运行应用程序
mvn spring-boot:run

贡献方式

  • 🐛 报告错误 - 帮助我们识别和修复问题。
  • 💡 建议功能 - 分享新功能的想法。
  • 📝 改进文档 - 帮助他人理解项目。
  • 🔧 提交代码 - 修复错误或实现新功能。
  • 🧪 编写测试 - 提高测试覆盖率和可靠性。
  • 🎨 UI/UX 改进 - 增强用户体验。

社区

  • GitHub 讨论：提问和分享想法。
  • 问题：报告错误和请求功能。
  • 拉取请求：贡献代码改进。
  • Wiki：协作编写文档。

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

🙏 致谢

  • Spring AI 团队 提供了出色的 MCP 框架。
  • Model Context Protocol 提供了标准化的 AI 集成协议。
  • Anthropic 提供了 Claude Desktop 和 AI 助手功能。
  • OpenJDK 社区 提供了强大的 Java 平台。

📞 支持

Made with ❤️ for the AI and Java communities

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client