arthas-mcp

Let AI agents diagnose live JVMs. An MCP server that connects Claude (or any MCP client) to Alibaba Arthas, the battle-tested Java diagnostics tool — no restarts, no code changes, no redeploy.

中文文档

Ask your AI things like:

"Why is this service burning 200% CPU?" → it pulls the dashboard, finds the hottest threads, reads their stacks, and tells you which method is spinning.

"What arguments is OrderService.createOrder actually receiving in production?" → it sets up a watch, captures live invocations, and shows you real params and return values.

"Is the deployed class the version we think it is?" → it decompiles the loaded bytecode with jad and diffs it against your source.

How it works

Claude / MCP client  ──stdio──▶  arthas-mcp  ──HTTP──▶   Arthas (sync commands)
                                             ──WebSocket──▶ Arthas (streaming: watch/trace/monitor)
                                                              │
                                                              ▼
                                                        target JVM

Sync commands (dashboard, thread, jad, …) go over Arthas' HTTP API and return directly. Streaming commands (watch, trace, stack, monitor, tt -t) run as background jobs over WebSocket: output streams to a local log file, the tool waits up to awaitMs (default 5s) and returns results inline if the command finished — otherwise it hands back a job ID you can poll with arthas_read_log and cancel with arthas_stop_job. Long captures never block the conversation and never flood the context window (every response is capped, ~16k chars, configurable).

Quick start

1. Attach Arthas to your Java process

curl -O https://arthas.aliyun.com/arthas-boot.jar
java -jar arthas-boot.jar        # pick the target JVM from the list

That's it — Arthas serves its HTTP/WebSocket API on 127.0.0.1:8563 by default, which is exactly where arthas-mcp looks.

2. Add the MCP server

Claude Code

claude mcp add arthas -- npx -y arthas-mcp

Claude Desktop / Windsurf / Cursor (mcpServers config):

{
  "mcpServers": {
    "arthas": {
      "command": "npx",
      "args": ["-y", "arthas-mcp"],
      "env": {
        "ARTHAS_WS_URL": "ws://127.0.0.1:8563/ws"
      }
    }
  }
}

env is optional if Arthas runs on the default port.

3. Ask questions

Open your client and ask anything about the running JVM. The AI picks the right Arthas commands by itself.

Diagnosing a JVM in Kubernetes

Arthas must run inside the pod; then port-forward its API port:

# copy + attach arthas inside the pod (or bake it into your image)
kubectl exec -it <pod> -- sh -c 'curl -sO https://arthas.aliyun.com/arthas-boot.jar && java -jar arthas-boot.jar 1 --target-ip 0.0.0.0'

# expose the HTTP/WS API locally
kubectl port-forward <pod> 8563:8563

arthas-mcp on your laptop now talks to the JVM in the cluster.

Tools

Tool	What it does
arthas_cookbook	Start here for a symptom — proven step-by-step recipes (high CPU, memory leak, slow requests, worker-pool exhaustion, deadlocks, HikariCP, Spring, flame graphs). Human-readable copy: COOKBOOK.md
arthas_dashboard	Threads / memory / GC / runtime overview
arthas_thread	Thread list, top-N CPU, blocking threads, per-thread stacks
arthas_jvm, arthas_memory	JVM info and detailed memory breakdown
arthas_sc, arthas_sm	Search loaded classes / methods
arthas_jad	Decompile a loaded class (see what's actually deployed)
arthas_watch	Capture live method params / return values / exceptions ⏳
arthas_trace	Call-path timing — find the slow hop ⏳
arthas_stack	Who calls this method, live ⏳
arthas_monitor	Invocation stats: QPS, RT, failure rate ⏳
arthas_tt	Time Tunnel: record invocations, replay them later ⏳ (record mode)
arthas_ognl, arthas_getstatic	Evaluate OGNL / read static fields
arthas_classloader	Classloader hierarchy and leaks
arthas_profiler	async-profiler: CPU / alloc / lock flame graphs
arthas_heapdump	Dump the heap to a file
arthas_exec	Escape hatch: run any raw Arthas command
arthas_async_jobs, arthas_read_log, arthas_stop_job	Manage background jobs ⏳
arthas_set_config	Repoint to another Arthas instance mid-session
arthas_version, arthas_help	Meta

⏳ = streaming command, runs as a background job (see How it works).

Configuration

Env var / flag	Default	Meaning
ARTHAS_WS_URL	ws://127.0.0.1:8563/ws	Arthas WebSocket endpoint (HTTP API URL is derived)
ARTHAS_HTTP_URL	derived	Alternative: give the HTTP API URL instead
ARTHAS_MAX_OUTPUT	16000	Per-response character cap before truncation
--url <url> / positional URL	—	CLI override, takes precedence over env

Background-job logs live under $TMPDIR/arthas-mcp-logs/.

Security

Arthas is a full-power diagnostics tool: ognl evaluates arbitrary expressions inside the target JVM, and arthas_exec runs any Arthas command. Only point arthas-mcp at JVMs you are authorized to debug, keep the Arthas port bound to localhost (or reached via kubectl port-forward / SSH tunnel), and never expose 8563 to untrusted networks.

Development

git clone https://github.com/HeavenC/arthas-mcp.git
cd arthas-mcp
npm install
npm run build        # tsc → dist/
node dist/index.js   # speaks MCP on stdio

The whole server is a single file: src/index.ts.

License

MIT