**Languages:** English | [简体中文](README.zh-CN.md)

<div align="center">
  <img src="assets/logo.svg" width="132" alt="arthas-mcp logo" />
  <h1>arthas-mcp</h1>
  <p><b>Let AI agents debug your running Java services with Arthas</b><br/>zero config · JVM auto-discovery · any MCP client</p>
  <p>
    <a href="https://github.com/x0c/arthas-mcp/actions/workflows/ci.yml"><img src="https://github.com/x0c/arthas-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License: MIT"></a>
    <img src="https://img.shields.io/badge/node-%3E%3D18-blue.svg" alt="Node >= 18">
    <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg" alt="Platforms">
  </p>
</div>

An [MCP](https://modelcontextprotocol.io) server that bridges [Alibaba Arthas](https://github.com/alibaba/arthas) into Claude Code, Cursor, Codex and any other MCP-capable AI assistant. It **scans local JVMs every 15 seconds, filters out IDE/build daemons, attaches Arthas automatically, and exposes ready-to-use diagnostic tools** — so you can just ask your agent *"why is the order service slow?"* and it can run `thread`, `trace`, `watch` and `ognl` on the live process.

```
AI agent ──stdio/HTTP──> arthas-mcp ──auto-attach──> Arthas agent ──> your JVM
                             ▲
                    jps discovery every 15s
```

## How it compares

| | arthas-mcp (this project) | Official [arthas-mcp-server] | Community wrappers |
|---|---|---|---|
| Setup | **Zero config** — just start it | Java module running inside the target JVM | Start Arthas WebConsole manually, then point a URL |
| Target discovery | **Automatic** (jps scan + blacklist) | None (it *is* the app) | Manual |
| Language | Node (no Java code to maintain) | Java | varies |
| Best for | Debugging any local service from your editor | In-process, production-hosted diagnostics | Quick one-offs |

[arthas-mcp-server]: https://arthas.aliyun.com/en/doc/mcp-server.html

## Features

- **Zero-config discovery** — finds business JVMs via `jps`, skips IntelliJ / Gradle / Maven / language-server daemons via a built-in blacklist
- **Auto attach & reattach** — starts `arthas-boot` per process on a managed port pool, and reattaches when an agent drops
- **Sync + async command execution** — short commands (`version`, `sc`, `sm`, `ognl`) return directly; long-running ones (`trace`, `watch`, `monitor`) stream via `pull_results` and can be interrupted
- **stdio and HTTP modes** — one instance per client session (stdio), or a shared long-running service (`--http`) with `/mcp` + `/healthz`
- **Friendly output** — Arthas job results are collapsed into clean text an LLM can read directly
- **Cross-platform** — macOS, Linux and Windows (per-OS process introspection: `/proc`, `ps`, PowerShell CIM)

## Supported platforms

| Platform | Status |
|---|---|
| macOS | ✅ |
| Linux | ✅ |
| Windows | ✅ (requires JDK `jps`/`java` on `PATH`) |

Requirements: **Node ≥ 18**, a **JDK** (for `jps` and `java`), and [Arthas](https://arthas.aliyun.com/doc/download.html) — auto-detected from `~/.arthas/lib` (i.e. it is already installed if you have run `arthas-boot` before), or point `ARTHAS_BOOT_JAR` at `arthas-boot.jar`. All dependencies are free and open source.

## Install

### Run without installing (recommended)

```bash
npx -y github:x0c/arthas-mcp --version
```

### Install globally

```bash
npm install -g github:x0c/arthas-mcp
arthas-mcp --version
```

> Same commands on macOS, Linux and Windows. Once published to the npm registry, both shorten to `npx -y arthas-mcp` / `npm install -g arthas-mcp`.

### From source

```bash
git clone https://github.com/x0c/arthas-mcp.git
cd arthas-mcp && npm install
node cli/arthas-mcp.mjs --version
```

## Configure your MCP client

Claude Code:

```bash
claude mcp add arthas -- npx -y github:x0c/arthas-mcp
```

Cursor / any client that reads an `mcpServers` JSON block:

```json
{
  "mcpServers": {
    "arthas": {
      "command": "npx",
      "args": ["-y", "github:x0c/arthas-mcp"]
    }
  }
}
```

Shared daemon mode (one instance for all clients):

```json
{
  "mcpServers": {
    "arthas": {
      "command": "npx",
      "args": ["-y", "github:x0c/arthas-mcp", "--http"],
      "url": "http://127.0.0.1:8580/mcp"
    }
  }
}
```

## Usage

Start your Java service, wait a few seconds, then ask the agent — or call the tools yourself:

| Tool | Purpose |
|---|---|
| `list_agents` | List discovered services and their online status — call this first |
| `exec` | Run a short Arthas command synchronously (`version`, `sc`, `sm`, `ognl …`); failures return the exit code **and the exception summary**, no extra watch needed |
| `watch_and_trigger` | One-shot "set up watch → trigger one call → collect results" — replaces the async_exec + exec + pull_results round-trip when you want to observe a method's real params/return/exception |
| `async_exec` | Submit a long-running command (persistent `watch -f`, `monitor`), returns `sessionId` / `consumerId` |
| `pull_results` | Poll results of an `async_exec` |
| `interrupt_job` | Stop a running persistent job |

Example session:

```text
You:  why is the order service slow?
Agent: (list_agents) → order-service is online on port 18501
       (exec order-service "thread -n 3")     → hottest threads
       (watch_and_trigger order-service
          watch "watch *OrderService create '{params, returnObj, throwExp}' -x 2 -n 1"
          trigger "ognl …create(#req)")            → one-shot observe + trigger
```

## Configuration

Precedence: CLI args > environment variables > `~/.config/arthas-mcp/config.json` > defaults.

| Source | What |
|---|---|
| `config.json` | `host`, `port`, `scanInterval`, `attachTimeout`, `requestTimeout`, `portMin`/`portMax`, `stripPrefixes` (list of prefixes stripped from derived service ids) |
| `aliases.json` | Map a detected service name to a friendlier agent id |
| `ARTHAS_MCP_PORT` / `ARTHAS_MCP_HOST` | HTTP mode bind address |
| `ARTHAS_MCP_CONFIG_DIR` | Move the whole config directory |
| `ARTHAS_BOOT_JAR` | Explicit path to `arthas-boot.jar` |
| `--scan-interval <ms>` | JVM scan interval (default 15000) |

## FAQ

**Why not the official arthas-mcp-server?** They solve different problems: the official one is an in-process Java module for production-hosted diagnostics, this project is a local-side wrapper that discovers and attaches to *any* JVM without touching the app. They can coexist.

**Does it modify my application?** It attaches the Arthas agent to the running JVM (like running `arthas-boot` by hand) — no restart, no code change. Stop the tool or run `stop` to detach.

**Is it safe to point an LLM at production?** It gives the agent the same power Arthas has (including bytecode-level watch). Point it at local/dev JVMs, and use read-only judgement in production.

## License

[MIT](LICENSE)