Arthas MCP Server 完整使用指南

1. 工作原理

先理解一个关键点：arthas-mcp-server 不是一个独立进程。

┌─────────────┐   MCP (streamableHttp)   ┌──────────────────────────┐
│  AI 客户端   │ ───────────────────────▶ │  目标 JVM (如 math-game) │
│ (WorkBuddy  │   http://localhost:8563  │  ┌────────────────────┐  │
│  等)        │                          │  │ arthas agent       │  │
└─────────────┘                          │  │ (attach 时注入)     │  │
                                         │  │  - telnet :3658     │  │
                                         │  │  - http  :8563/mcp  │  │
                                         │  └────────────────────┘  │
                                         │  ┌────────────────────┐  │
                                         │  │ 你的业务代码        │  │
                                         │  └────────────────────┘  │
                                         └──────────────────────────┘
  • Arthas 以 agent 形式 attach 到目标 Java 进程，之后在目标进程内部启动 HTTP 服务，默认端口 8563，MCP 路径为 /mcp（由 arthas.properties 中 arthas.mcpEndpoint=/mcp 控制）。
  • 所以「启动 MCP server」= 「找一个目标 JVM + 把 arthas attach 上去」。
  • 目标 JVM 停止（或调用 stop 工具），MCP 服务随之消失。

2. 环境准备

依赖 要求 检查命令
Java JDK 8+（目标进程和 attach 方都需要） java -version
curl 用于下载和探活 curl --version
unzip 解压安装包 unzip -v
telnet 仅 as.sh 启动脚本检查用（macOS 通常没有，见 FAQ） command -v telnet

JDK 17+ 才会构建/启用 MCP 相关集成测试模块，但运行时 JDK 8+ 即可。

3. 下载与安装

3.1. 下载发行包

从 GitHub Release 下载（不要本地编译，全量构建很慢）：

# 下载（可换成其他版本号，见 https://github.com/alibaba/arthas/releases）
curl -sSL -o /tmp/arthas-bin.zip \
https://github.com/alibaba/arthas/releases/download/arthas-all-4.3.5/arthas-bin.zip

包大小约 16 MB，包含：arthas-core.jar、arthas-agent.jar、arthas-boot.jar、arthas-client.jar、arthas-spy.jar、math-game.jar（演示用）、as.sh、arthas.properties、lib/（vmtool native 库）、async-profiler/ 等。

3.2. 安装到本地

Arthas 的启动脚本默认在 ~/.arthas/lib/<版本>/arthas/ 下寻找安装：

# 解压
unzip -q /tmp/arthas-bin.zip -d /tmp/arthas-dl

# 安装
ARTHAS_HOME=~/.arthas/lib/4.3.5/arthas

mkdir -p "$ARTHAS_HOME"
cp /tmp/arthas-dl/*.jar "$ARTHAS_HOME"/
cp /tmp/arthas-dl/arthas.properties /tmp/arthas-dl/logback.xml "$ARTHAS_HOME"/
cp -r /tmp/arthas-dl/lib /tmp/arthas-dl/async-profiler "$ARTHAS_HOME"/
cp /tmp/arthas-dl/as.sh "$ARTHAS_HOME"/
chmod +x "$ARTHAS_HOME"/as.sh

注意：包内自带的 install-local.sh 只拷贝 jar，不拷贝 as.sh，需要手动补（上面最后两行）。

3.3. 确认 MCP 配置已开启

检查 ~/.arthas/lib/4.3.5/arthas/arthas.properties，4.3.5 默认已开启，无需修改：

arthas.mcpEndpoint=/mcp # MCP 服务路径；不配置则不启用
arthas.mcpProtocol=STREAMABLE # STREAMABLE(有状态,默认) / STATELESS(无状态)
arthas.httpPort=8563 # HTTP 端口

4. 启动服务

4.1. 准备目标 JVM

MCP 是 attach 模式，先要有一个运行中的 Java 进程。没有现成应用时，用自带的演示程序：

# 演示程序 math-game：死循环做质因数分解，每秒一次
java -jar ~/.arthas/lib/4.3.5/arthas/math-game.jar

有真实应用就直接用它（Spring Boot fat jar、tomcat 进程均可）。

4.2. Attach Arthas

另开一个终端：

# 查找目标进程 PID
jps -l
# attach（--attach-only 表示只注入 agent，不进入交互式 telnet）
bash ~/.arthas/lib/4.3.5/arthas/as.sh --attach-only <pid>

成功标志：

Attaching to <pid> using version /Users/xxx/.arthas/lib/4.3.5/arthas...
Attach success.

macOS 用户注意：as.sh 启动时会硬性检查 telnet 命令是否存在，macOS 默认没有。用一个空壳脚本绕过：

mkdir -p /tmp/arthas-dl/bin
printf '#!/bin/bash\nexit 0\n' > /tmp/arthas-dl/bin/telnet
chmod +x /tmp/arthas-dl/bin/telnet
# 之后所有 as.sh 调用都带上 PATH 前缀
PATH=/tmp/arthas-dl/bin:$PATH bash ~/.arthas/lib/4.3.5/arthas/as.sh --attach-only <pid>

4.3. 验证服务

# 1) 端口在监听
lsof -iTCP:8563 -sTCP:LISTEN

# 2) MCP 握手（应返回 serverInfo: arthas-mcp-server）
curl -s -X POST http://localhost:8563/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"0.0.1"}}}'

正确响应（节选）：

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-03-26","serverInfo":{"name":"arthas-mcp-server","version":"4.3.5"}, ...}}

5. 配置 AI 客户端

5.1. WorkBuddy

编辑 ~/.workbuddy/mcp.json（没有则新建）：

{
  "mcpServers": {
    "arthas-mcp": {
      "type": "streamableHttp",
      "url": "http://localhost:8563/mcp",
      "timeout": 30000
    }
   }
}

然后在 WorkBuddy 中启用：左侧栏 专家・技能・连接器 → 连接器 → 右上角自定义连接器 → 配置 MCP，将 arthas-mcp 切到信任/启用状态。
验证：在对话里问「列出 arthas-mcp 提供的工具」或「查看当前 JVM 信息」。

5.2. Cherry Studio / Cline 等其他客户端

设置中添加 MCP 服务器：

{
  "mcpServers": {
    "arthas-mcp": {
    "type": "streamableHttp",
    "url": "http://localhost:8563/mcp"
    }
  }
}

6. 工具总览

共 32 个工具，与 Arthas 命令一一对应。

6.1.1. JVM 诊断（13 个）

工具 对应命令 说明
dashboard dashboard 实时 JVM/应用面板，可控制刷新间隔与次数
jvm jvm JVM 运行时完整信息
memory memory 内存使用情况（heap/nonheap/buffer 分区明细）
thread thread 线程信息与堆栈；blocking=true 找阻塞源，topN=N 找最忙线程
heapdump heapdump 导出堆转储，live=true 只含存活对象
vmtool vmtool 强制 GC、获取类实例、中断线程
vmoption vmoption 查看/动态修改 VM 参数
sysprop sysprop 查看/修改系统属性
sysenv sysenv 查看环境变量
perfcounter perfcounter JVM 性能计数器
mbean mbean 查看/监控 MBean 属性
getstatic getstatic 查看类静态字段，支持 OGNL 后处理
ognl ognl 执行任意 OGNL 表达式

6.1.2. Class / ClassLoader（8 个）

| 工具 | 对应命令 | 说明 |

| ------------- | ----------- | --------------------------------------------- |

| sc | sc | 搜索已加载类（详情含类加载器、注解、字段） |

| sm | sm | 搜索类的方法（签名、参数、注解） |

| jad | jad | 反编译指定类 |

| classloader | classloader | 类加载器统计/继承树/URL（mode=stats/tree/url-classes 等） |

| mc | mc | 内存编译器，.java → .class |

| redefine | redefine | 热更新类字节码 |

| retransform | retransform | 触发类重新转换 |

| dump | dump | 导出运行中的 class 字节码 |

6.1.3. 监控诊断（6 个，长耗时流式工具）

| 工具 | 对应命令 | 说明 |

| ---------- | -------- | --------------------------- |

| watch | watch | 观察方法入参/返回值/异常 |

| trace | trace | 方法内部调用链路耗时 |

| stack | stack | 方法被调用的调用路径 |

| monitor | monitor | 方法调用统计（次数/成功率/RT） |

| tt | tt | 时空隧道：记录、搜索、回放方法调用 |

| profiler | profiler | async-profiler 采样，输出火焰图/JFR |

6.1.4. 辅助工具（5 个）

| 工具 | 说明 |

| ------------- | ------------------------------------------------------------ |

| viewfile | 查看白名单目录内文件，支持 cursor 分段读取 |

| upload_file | 上传 .class/.java/.jfc 到目标 JVM（Base64），配合 mc/redefine/profiler |

| options | 查看/修改 Arthas 全局开关（unsafe、json-format、strict 等） |

| version | 查看 Arthas 版本 |

| stop | 彻底停止 Arthas（停完全部工具失效，慎用） |

7. 常用场景示例

以下均为对 AI 说自然语言即可完成的事情（AI 会翻译成对应 tool 调用）：

基础巡检

  • 「看下当前 JVM 内存占用和线程数」→ memory + thread

  • 「哪个线程 CPU 最高？打印它的堆栈」→ thread (topN=1)

  • 「当前 JVM 加载了多少个类？」→ classloader (mode=stats)

问题定位

  • 「demo.MathGame.primeFactors 每次调用的入参和返回值是什么」→ watch

  • 「primeFactors 内部每一步耗时多少，哪一步最慢」→ trace

  • 「谁在调用 primeFactors？」→ stack

  • 「监控 primeFactors 一分钟的调用次数和成功率」→ monitor

  • 「把刚才那次失败的调用重放一下」→ tt (replay)

代码诊断

  • 「反编译 demo.MathGame 看看运行中的真实代码」→ jad

  • 「搜一下 JVM 里所有加载的 StringUtils 类」→ sc *StringUtils

  • 「动态执行 @System@getProperty("user.dir")」→ ognl

热修复

  • 「我把修复后的类编译好上传进去热更新」→ upload_file + redefine

性能分析

  • 「对当前进程做 60 秒 CPU 采样，输出火焰图」→ profiler (action=start, duration=60, format=flamegraph)

提示：watch/trace/stack/monitor/tt 属于长耗时工具，都支持 numberOfExecutions（次数）和 timeout（秒）参数控制自动停止，默认超时 30 秒。

8. 可选：开启认证

默认本地无认证。如需开启，在 arthas.properties 中配置：


arthas.password=your-secure-password

然后 AI 客户端配置加上 headers（token 与密码完全一致）：


{

"mcpServers": {

"arthas-mcp": {

"type": "streamableHttp",

"url": "http://localhost:8563/mcp",

"headers": {

"Authorization": "Bearer your-secure-password"

}

}

}

}

9. 常见问题（FAQ）

Q1：curl 8563 返回 Connection refused？

MCP 服务随目标 JVM 存活。检查目标进程是否还在（jps -l），不在则重启应用并重新 attach。

Q2：macOS 报 Error: telnet is not installed？

见 4.2 节——放一个空壳 telnet 脚本到 PATH 里绕过 as.sh 的检查。

Q3：MCP 客户端报 session 失效 / 旧请求 404？

目标 JVM 重启过（或 arthas 重新 attach 过）会生成新进程、旧 session 全部失效。客户端重新 initialize 即可（WorkBuddy 会自动处理）。

Q4：想彻底停掉 Arthas？

  • 优雅方式：调用 MCP 的 stop 工具（它会先返回结果再延迟执行）；

  • 或者直接杀目标 JVM（kill <pid>），agent 随进程消亡。

Q5：viewfile 提示目录不在白名单？

默认只允许 ./arthas-output/ 和 ~/logs/。扩展方式：


export ARTHAS_MCP_VIEWFILE_ALLOWED_DIRS=/path/a,/path/b

Q6：怎么换成诊断我自己的应用？

对你的应用进程重复 4.2 节的 attach 即可。一个目标 JVM 一个 arthas 实例；换目标后 8563 指向新进程。

Q7：STATELESS 和 STREAMABLE 怎么选？

  • STREAMABLE（默认）：有状态，支持 watch/trace 等流式长命令和进度通知，交互式诊断用这个；

  • STATELESS：每请求独立，适合简单一次性查询，改 arthas.mcpProtocol=STATELESS。

9.1. 快速命令速查


# === 安装（一次性） ===

curl -sSL -o /tmp/arthas-bin.zip \

https://github.com/alibaba/arthas/releases/download/arthas-all-4.3.5/arthas-bin.zip

unzip -q /tmp/arthas-bin.zip -d /tmp/arthas-dl

ARTHAS_HOME=~/.arthas/lib/4.3.5/arthas

mkdir -p "$ARTHAS_HOME" && cp /tmp/arthas-dl/*.jar "$ARTHAS_HOME"/ \

&& cp /tmp/arthas-dl/arthas.properties /tmp/arthas-dl/logback.xml "$ARTHAS_HOME"/ \

&& cp -r /tmp/arthas-dl/lib /tmp/arthas-dl/async-profiler "$ARTHAS_HOME"/ \

&& cp /tmp/arthas-dl/as.sh "$ARTHAS_HOME"/ && chmod +x "$ARTHAS_HOME"/as.sh

# telnet 空壳（macOS）

mkdir -p /tmp/arthas-dl/bin && printf '#!/bin/bash\nexit 0\n' \

> /tmp/arthas-dl/bin/telnet && chmod +x /tmp/arthas-dl/bin/telnet

# === 每次启动 ===

java -jar ~/.arthas/lib/4.3.5/arthas/math-game.jar & # 目标 JVM（或你自己的应用）

jps -l # 找 PID

PATH=/tmp/arthas-dl/bin:$PATH bash ~/.arthas/lib/4.3.5/arthas/as.sh --attach-only <pid>

# === 验证 ===

curl -s -X POST http://localhost:8563/mcp \

-H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \

-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"0.0.1"}}}'

评论