Submit
HeavenC

arthas-mcp

Community HeavenC
Updated

arthas-mcp

npmlicensenode

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

MCP Server · Populars

MCP Server · New