arthas-mcp

语言： English | 简体中文

一个 MCP 服务器，将 Alibaba Arthas 桥接到 Claude Code、Cursor、Codex 及任何其他支持 MCP 的 AI 助手。它每 15 秒扫描本地 JVM，过滤掉 IDE/构建守护进程，自动挂载 Arthas，并提供开箱即用的诊断工具——所以你可以直接问 agent “订单服务为什么变慢了？”，它就能在运行中的进程上执行 thread、trace、watch 和 ognl。

AI agent ──stdio/HTTP──> arthas-mcp ──auto-attach──> Arthas agent ──> your JVM
                             ▲
                    jps discovery every 15s

对比

Related MCP server: Arthas MCP Server

特性

• 零配置发现 —— 通过 jps 查找业务 JVM，借助内置黑名单跳过 IntelliJ / Gradle / Maven / 语言服务器守护进程

• 自动挂载与重新挂载 —— 在受管端口池中为每个进程启动 arthas-boot，并在 agent 断开时重新挂载

• 同步 + 异步命令执行 —— 短命令（version、sc、sm、ognl）直接返回；长时间运行的命令（trace、watch、monitor）通过 pull_results 流式获取，并且可以中断

• stdio 与 HTTP 模式 —— 每个客户端会话一个实例（stdio），或共享的常驻服务（--http），提供 /mcp + /healthz

• 友好的输出 —— Arthas 任务结果被整理成简洁的文本，LLM 可以直接阅读

• 跨平台 —— macOS、Linux 和 Windows（按操作系统进行进程内省：/proc、ps、PowerShell CIM）

支持的平台

环境要求：Node ≥ 18、JDK（用于 jps 和 java），以及 Arthas——会自动从 ~/.arthas/lib 检测（也就是说，如果你之前运行过 arthas-boot，它就已经安装好了），或者将 ARTHAS_BOOT_JAR 指向 arthas-boot.jar。所有依赖都是免费且开源的。

安装

无需安装直接运行（推荐）

npx -y github:x0c/arthas-mcp --version

全局安装

npm install -g github:x0c/arthas-mcp
arthas-mcp --version

macOS、Linux 和 Windows 上命令相同。一旦发布到 npm 仓库，两者都可简化为 npx -y arthas-mcp / npm install -g arthas-mcp。

从源码安装

git clone https://github.com/x0c/arthas-mcp.git
cd arthas-mcp && npm install
node cli/arthas-mcp.mjs --version

配置你的 MCP 客户端

Claude Code：

claude mcp add arthas -- npx -y github:x0c/arthas-mcp

Cursor / 任何读取 mcpServers JSON 块的客户端：

{
  "mcpServers": {
    "arthas": {
      "command": "npx",
      "args": ["-y", "github:x0c/arthas-mcp"]
    }
  }
}

共享守护进程模式（所有客户端共用一个实例）：

{
  "mcpServers": {
    "arthas": {
      "command": "npx",
      "args": ["-y", "github:x0c/arthas-mcp", "--http"],
      "url": "http://127.0.0.1:8580/mcp"
    }
  }
}

使用方法

启动你的 Java 服务，等待几秒钟，然后让 agent 来处理——或者你自己调用这些工具：

示例会话：

You:  why is the order service slow?
Agent: (list_agents) → order-service is online on port 18501
       (exec order-service "thread -n 3")     → hottest threads
       (async_exec order-service "trace *OrderService create") → submits trace
       (pull_results …)                       → shows the slow call chain

配置

优先级：命令行参数 > 环境变量 > ~/.config/arthas-mcp/config.json > 默认值。

常见问题

为什么不用官方的 arthas-mcp-server？ 它们解决的是不同的问题：官方版是运行在进程内的 Java 模块，用于生产环境诊断；本项目是本地侧的包装器，可以发现并挂载到任何 JVM，而无需改动应用。两者可以共存。

它会修改我的应用吗？ 它会把 Arthas agent 挂载到正在运行的 JVM 上（就像手动运行 arthas-boot 一样）——无需重启，无需改代码。停止该工具或运行 stop 即可解除挂载。

让 LLM 指向生产环境安全吗？ 它赋予了 agent 与 Arthas 相同的能力（包括字节码级别的 watch）。请将其指向本地/开发环境的 JVM，并在生产环境中仅做只读判断。

许可证

MIT