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

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