arthas-mcp

Languages: English | 简体中文

An MCP server that bridges 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

Related MCP server: Arthas MCP Server

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

Requirements: Node ≥ 18, a JDK (for jps and java), and Arthas — 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)

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

Install globally

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

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:

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

Cursor / any client that reads an mcpServers JSON block:

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

Shared daemon mode (one instance for all clients):

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

Example session:

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
       (async_exec order-service "trace *OrderService create") → submits trace
       (pull_results …)                       → shows the slow call chain

Configuration

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

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