# arthas-mcp

[![npm](https://img.shields.io/npm/v/arthas-mcp)](https://www.npmjs.com/package/arthas-mcp)
[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)

**Let AI agents diagnose live JVMs.** An [MCP](https://modelcontextprotocol.io) server that connects Claude (or any MCP client) to [Alibaba Arthas](https://arthas.aliyun.com/en/), the battle-tested Java diagnostics tool — no restarts, no code changes, no redeploy.

[中文文档](README.zh-CN.md)

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

```bash
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**

```bash
claude mcp add arthas -- npx -y arthas-mcp
```

**Claude Desktop / Windsurf / Cursor** (`mcpServers` config):

```json
{
  "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:

```bash
# 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](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](#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

```bash
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`](src/index.ts).

## License

[MIT](LICENSE)