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

Related MCP server: Alibaba Cloud FC MCP Server

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

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

Configuration

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