π¦
Arthas MCP Proxy
Enables dynamic SSH connection to servers for real-time JVM diagnostics using Arthas, allowing operations like thread dump, heap inspection, and method watching through MCP tools.
0 installs
Trust: 34 β Low
Blockchain
Ask AI about Arthas MCP Proxy
Powered by Claude Β· Grounded in docs
I know everything about Arthas MCP Proxy. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Loading tools...
Reviews
Documentation
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
