Arthas MCP Proxy

An Arthas diagnostic proxy server based on MCP (Model Context Protocol), supporting dynamic SSH connections to any server for real-time JVM diagnostics within Claude conversations.

Features

• Dynamic In-Conversation Connection: Directly pass SSH address, username, and password/key to connect to target servers in real-time.

• Multi-Process Parallel Diagnostics: Each JVM process has an independent Arthas agent, allowing zero-latency switching between PIDs.

• Automatic Connection Pooling: Caches SSH connections by user@host:port, with automatic reclamation after 5 minutes of inactivity.

• Automatic Arthas Attach: Automatically attaches in the background upon the first use of a target PID, with subsequent reuse.

• SSE Remote Deployment: Supports persistent deployment in HTTP SSE mode, allowing Claude to connect via URL.

• Offline Build Support: Enables Docker builds in air-gapped environments via pre-downloaded whl packages.

Related MCP server: javaperf

MCP Tools List

Concurrent Diagnostic Model

Important: Each JVM process requires an independent Arthas agent instance

PID 1234 (web)    <---> Arthas agent (port 3658)
PID 5678 (cpu)    <---> Arthas agent (port 3660)  
PID 9012 (memory) <---> Arthas agent (port 3661)

• First Use: Automatic background attach, Arthas automatically assigns a port (approx. 5 seconds).

• Subsequent Switching: Directly connects to an existing agent with zero latency.

• Multi-Process Support: Can keep multiple agents running simultaneously and switch between them at will.

• Resource Usage: Each agent consumes approximately 20-30MB of memory; it is recommended to keep the count <= 10 simultaneously.

• Release: Automatically cleans up when executing stop via exec_command or when disconnecting SSH.

Tech Stack

Quick Start

1. Online Build (Networked Environment)

docker build -t arthas-mcp-proxy .
# 或
docker-compose up -d

2. Offline Build (Air-gapped Environment)

Step 1: Pre-download dependencies on a machine with internet access

bash download-packages.sh
# 完成后 packages/ 目录包含所有 .whl 文件

Step 2: Package and transfer to the internal network

zip -r arthas-mcp-proxy.zip arthas-mcp-proxy/
# 通过 U 盘/SCP 传入内网服务器

Step 3: Build in the internal network

cd arthas-mcp-proxy
docker build --build-arg PIP_SOURCE=offline -t arthas-mcp-proxy .
# 或
PIP_SOURCE=offline docker-compose up -d --build

3. Claude Configuration

SSE Mode (Remote Deployment):

{
  "mcpServers": {
    "arthas": {
      "type": "sse",
      "url": "http://your-server-ip:8000/sse"
    }
  }
}

stdio Mode (Local Embedding):

{
  "mcpServers": {
    "arthas": {
      "command": "python",
      "args": ["/path/to/main.py", "--transport", "stdio"]
    }
  }
}

Usage Example

In a Claude conversation:

连接到 192.168.1.100，用户 root，密码 xxx，查看上面的 Java 进程。

Claude will automatically call connect_ssh -> list_java_processes.

Then:

查看 PID 1234 的线程栈 top 10，然后查看 PID 5678 的内存情况。

Claude will automatically switch diagnostics between multiple PIDs, attaching automatically upon the first use of each PID and reusing it thereafter.

Project Structure

arthas-mcp-proxy/
├── main.py                  # MCP Server 入口（SSE + stdio 双模式）
├── ssh_pool.py              # SSH 连接池（动态连接 + session 复用）
├── arthas_client.py         # Arthas 命令封装（多 PID 并行支持）
├── requirements.txt         # Python 依赖
├── Dockerfile               # 双模式构建 Dockerfile
├── docker-compose.yml       # Docker Compose 配置
├── download-packages.sh     # 外网预下载脚本
├── packages/                # 离线 whl 包目录
└── README.md                # 本文档

Target Machine Requirements

• Arthas installed (/opt/arthas/as.sh or custom path)

• SSH accessible, with the running user having permissions to attach to the target JVM

• jps command available (included with JDK)

License

MIT License