Languages: English | 简体中文

arthas-mcp

Let AI agents debug your running Java services with Arthas
zero config · JVM auto-discovery · any MCP client

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

	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

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 — 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:

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:

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