arthas-mcp

언어: English | 简体中文

MCP 서버로 Alibaba Arthas를 Claude Code, Cursor, Codex 및 기타 MCP 지원 AI 어시스턴트에 연결합니다. 로컬 JVM을 15초마다 스캔하고 IDE/빌드 데몬을 걸러 내며, Arthas를 자동으로 연결하고 바로 사용할 수 있는 진단 도구를 제공합니다 — 에이전트에게 *"주문 서비스가 왜 느리지?"*라고 묻기만 하면 에이전트는 실행 중인 프로세스에서 thread, trace, watch, ognl을 실행할 수 있습니다.

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

비교

Related MCP server: Arthas MCP Server

기능

• 제로 구성 발견 — jps로 비즈니스 JVM을 찾고 내장 블랙리스트로 IntelliJ / Gradle / Maven / 언어 서버 데몬을 건너뜁니다

• 자동 연결 및 재연결 — 관리되는 포트 풀에서 프로세스마다 arthas-boot를 시작하고 에이전트가 끊기면 다시 연결합니다

• 동기 + 비동기 명령 실행 — 짧은 명령(version, sc, sm, ognl)은 직접 반환하고, 오래 실행되는 명령(trace, watch, monitor)은 pull_results로 스트리밍되며 중단할 수 있습니다

• stdio 및 HTTP 모드 — 클라이언트 세션당 하나의 인스턴스(stdio), 또는 /mcp + /healthz가 있는 공유 장기 실행 서비스(--http)

• 친숙한 출력 — Arthas 작업 결과는 LLM이 직접 읽을 수 있는 깔끔한 텍스트로 요약됩니다

• 크로스 플랫폼 — macOS, Linux 및 Windows (OS별 프로세스 내부 조사: /proc, ps, PowerShell CIM)

지원 플랫폼

요구 사항: Node ≥ 18, JDK(jps 및 java용), Arthas — ~/.arthas/lib에서 자동 감지됩니다(즉, 이전에 arthas-boot를 실행한 적이 있다면 이미 설치되어 있음). 또는 ARTHAS_BOOT_JAR을 arthas-boot.jar로 지정하세요. 모든 종속성은 무료이며 오픈 소스입니다.

설치

설치 없이 실행 (권장)

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

전역 설치

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

macOS, Linux, Windows에서 동일한 명령어입니다. npm 레지스트리에 게시되면 둘 다 npx -y arthas-mcp / npm install -g arthas-mcp로 단축됩니다.

소스에서 빌드

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

MCP 클라이언트 구성

Claude Code:

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

Cursor / mcpServers JSON 블록을 읽는 모든 클라이언트:

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

공유 데몬 모드 (모든 클라이언트에 대해 하나의 인스턴스):

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

사용법

Java 서비스를 시작하고 몇 초 기다린 다음 에이전트에게 물어보세요 — 또는 직접 도구를 호출하세요:

예시 세션:

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

구성

우선순위: CLI 인자 > 환경 변수 > ~/.config/arthas-mcp/config.json > 기본값.

FAQ

왜 공식 arthas-mcp-server를 사용하지 않나요? 서로 다른 문제를 해결합니다. 공식 버전은 프로덕션 환경 진단을 위한 프로세스 내 Java 모듈이고, 이 프로젝트는 앱을 건드리지 않고 모든 JVM을 발견하고 연결하는 로컬 측 래퍼입니다. 둘은 공존할 수 있습니다.

내 애플리케이션을 수정하나요? 실행 중인 JVM에 Arthas 에이전트를 연결합니다(arthas-boot를 직접 실행하는 것과 같음) — 재시작도, 코드 변경도 없습니다. 도구를 중지하거나 stop을 실행하면 연결이 해제됩니다.

LLM을 프로덕션에 연결해도 안전한가요? Arthas가 가진 것과 동일한 권한(바이트코드 수준 watch 포함)을 에이전트에 부여합니다. 로컬/개발 JVM에 연결하고, 프로덕션에서는 읽기 전용 판단을 사용하세요.

라이선스

MIT