Skip to main content
Glama
deenesjakoruzh
narcissux

Arthas MCP Proxy

by narcissux
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Arthas MCP Proxy

MCP Server for JVM diagnostics via SSH + Arthas.

Provides 26+ diagnostic tools through the Model Context Protocol (MCP), enabling AI assistants to perform thread dumps, heap analysis, method tracing, CPU profiling, and more on remote Java processes.

Features

  • Full Arthas command suite — thread, trace, watch, heapdump, profiler, jad, etc.

  • Multi-target SSH — connect to multiple JVM hosts from a single server

  • Cross-user diagnosis — automatically uses sudo -u <owner> when SSH user != process owner

  • Concurrent-safe — per-PID attach locks + three-level reuse (cache → detect → attach)

  • SSE & stdio transports — works with Cursor, Claude Desktop, and other MCP clients

Related MCP server: javaperf

Quick Start

Docker (recommended)

docker run -p 8000:8000 ghcr.io/narcissux/arthas-mcp-proxy:latest

From source

git clone https://github.com/narcissux/arthas-mcp-proxy.git
cd arthas-mcp-proxy
pip install -e ".[dev]"
python -m arthas_mcp_proxy --transport sse --port 8000

Cursor / MCP Client configuration

{
  "mcpServers": {
    "arthas": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Available Tools

Tool

Purpose

connect_ssh

Establish SSH connection to target server

list_java_processes

List Java processes with Arthas status

thread_dump

Thread dump (top N by CPU)

heap_info

Memory dashboard

watch_method

Watch method params/return values

exec_command

Universal Arthas command executor (26+ commands)

install_arthas

Install Arthas on target server

disconnect_ssh

Disconnect and release resources

Development

Running tests

# Unit tests only (mocked, no external dependencies)
pytest tests/ --ignore=tests/integration/

# Integration tests with auto-managed Docker target (recommended)
pytest tests/integration/ -m integration -v --docker-target

# Integration tests against a remote target (env vars required)
export TEST_SSH_HOST=your-server
export TEST_SSH_USER=your-username
export TEST_SSH_PASSWORD=your-password
pytest tests/integration/ -m integration -v

# Manual two-step Docker target
docker compose -f docker-compose.test.yml up --build -d
export TEST_SSH_HOST=localhost TEST_SSH_USER=testuser TEST_SSH_PASSWORD=testpass
pytest tests/integration/ -m integration -v
docker compose -f docker-compose.test.yml down --volumes

Code quality

# Install dev dependencies
pip install -e ".[dev]"

# Run lint
ruff check src/ tests/
ruff format --check src/ tests/

# Run type check
mypy src/arthas_mcp_proxy

# Run tests
pytest -v

# Run with coverage
pytest --cov=arthas_mcp_proxy --cov-report=html

Project Structure

.
├── src/
│   └── arthas_mcp_proxy/
│       ├── __init__.py          # Package init
│       ├── __main__.py          # python -m arthas_mcp_proxy
│       ├── server.py            # MCP server & tools
│       ├── arthas_client.py     # Arthas attach & command execution
│       ├── ssh_pool.py          # SSH connection pool
│       └── decorators.py        # @require_session and other decorators
├── tests/
│   ├── conftest.py              # Shared fixtures (mock SSH session, state cleanup)
│   ├── test_decorators.py       # @require_session tests
│   ├── test_arthas_client.py    # Concurrency & logic tests
│   ├── test_ssh_pool.py         # Connection pool tests
│   └── integration/
│       ├── conftest.py          # Integration env validation & Docker check
│       └── test_real_jvm.py     # Real JVM diagnostic tests via SSH
├── pyproject.toml               # Project config, deps, tool settings
├── entrypoint.sh                # Test target container startup script
├── Dockerfile
├── docker-compose.yml           # Production deployment
├── docker-compose.test.yml      # Test infrastructure (SSH + Java container)
├── Dockerfile.test-target       # Test target image (Java + math-game.jar)
└── README.md

Test categories

Category

Command

Requirements

Unit tests

pytest tests/ --ignore=tests/integration/

None (fully mocked)

Integration (remote)

pytest tests/integration/ -m integration

SSH target with Java

Integration (Docker)

docker compose -f docker-compose.test.yml up + pytest

Docker daemon

Environment variables for integration tests

Variable

Required

Default

Description

TEST_SSH_HOST

Yes

—

Target hostname or IP

TEST_SSH_USER

Yes

—

SSH username

TEST_SSH_PASSWORD

Yes

—

SSH password

TEST_SSH_PORT

No

22

SSH port

TEST_TARGET_PID

No

auto

Specific PID to diagnose

Security: Never commit credentials. Use environment variables or a .env file (ignored by .gitignore).

License

MIT

This server cannot be deployed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • javaperf

    theSharque
    A
    license
    A
    quality
    D
    maintenance
    MCP server for profiling Java applications via JDK utilities (jcmd, jfr, jps). Enables AI assistants to diagnose performance, analyze threads, and inspect JFR recordings without manual CLI usage.
    26
    26
    10
    MIT

  • SSH MCP Server

    honwee
    A
    license
    A
    quality
    D
    maintenance
    Enables AI tools to manage SSH connections, execute commands, transfer files, and perform remote server diagnostics via MCP protocol.
    17
    13
    MIT

  • arthas-mcp

    HeavenC
    A
    license
    A
    quality
    C
    maintenance
    A Model Context Protocol server that connects AI agents to live Java processes via Alibaba Arthas, enabling real-time diagnostics, debugging, and performance analysis without code changes.
    25
    MIT