JVM-MCP

Self-contained Java 21 Model Context Protocol (MCP) server with zero runtime framework overhead.
Provide Claude, Cursor, and AI coding assistants with real-time runtime context on memory, threads, Spring beans, and database connection pools without modifying target application code.

---

Table of Contents

• Why This Exists
• How It Works
• Quickstart: MCP Client Setup
• CLI Usage
• Exposed MCP Tools
• Architectural Principles
• Security & Defense Boundaries
• Platform & Runtime Compatibility Matrix
• Known Limitations and Trade-offs
• Contributing & Governance
• License

---

Why This Exists

When debugging backend Java services with LLMs, static source code only tells half the story:

1. Deadlocks, thread starvation, and runaway thread allocations cannot be deduced purely from code syntax.
2. Memory leaks in Old Gen or sudden allocation spikes in Eden require live heap inspection.
3. Spring Boot bean initialization orders and active HikariCP pool saturation require dynamic runtime context.

Existing tools require heavy external APM agents, modifying pom.xml files to expose open Actuator/JMX endpoints, or manually running jstack / jcmd in a terminal and copy-pasting megabytes of unformatted text into prompts.

JVM-MCP attaches locally to target JVM processes using the standard JDK Attach API (com.sun.tools.attach), dynamically exposes diagnostic data over the standardized Model Context Protocol (JSON-RPC 2.0 stdio), and requires zero modifications to target applications.

---

How It Works

Distributed as a standalone multi-platform bundle with a stripped custom runtime via jlink/jpackage. No pre-installed JDK is required on the client machine.

+-----------------------------------------+
|      Claude Desktop / Cursor / IDE      |
+-----------------------------------------+
                     | JSON-RPC 2.0 (stdio)
                     v
+-----------------------------------------+
|               jvm-mcp                   | (Virtual Threads, < 150ms cold start)
+-----------------------------------------+
                     | Attach API / Dynamic JMX
                     v
+-----------------------------------------+
|       Target Java App (PID 45231)       | (Zero modifications or dependencies)
+-----------------------------------------+

---

Installation

Pre-built standalone distributions include a minimal modular JRE via jlink (Linux/macOS) and jpackage (Windows). No pre-installed JDK is required on the host system.

One-Line Universal Installer (Linux & macOS)

curl -fsSL https://raw.githubusercontent.com/oscarbol09/jvm-mcp/main/install.sh | bash

The script automatically detects your platform architecture (linux-amd64, linux-aarch64, macos-aarch64, macos-amd64), verifies the cryptographic SHA-256 checksum against the release manifest, and unpacks jvm-mcp into ~/.local/bin.

Homebrew (macOS & Linux)

brew install oscarbol09/tap/jvm-mcp

Pre-Compiled Standalone Archives

Download release packages and corresponding .sha256 checksums from GitHub Releases:

Verify checksum and unpack:

# Example for Linux
sha256sum -c jvm-mcp-linux-amd64.tar.gz.sha256
tar -xzf jvm-mcp-linux-amd64.tar.gz
./jvm-mcp --version

Building From Source

Requires JDK 21+ and Git:

git clone https://github.com/oscarbol09/jvm-mcp.git
cd jvm-mcp
./mvnw clean package -DskipTests

# Run the packaged fat JAR directly:
java -jar mcp-server/target/jvm-mcp-server-1.1.0-SNAPSHOT.jar --version

---

Quickstart: MCP Client Setup

Claude Desktop

Add jvm-mcp to your claude_desktop_config.json:

{
  "mcpServers": {
    "jvm-mcp": {
      "command": "jvm-mcp",
      "args": ["serve"]
    }
  }
}

(If running from the repository fat JAR directly: "command": "java", "args": ["-jar", "/path/to/jvm-mcp-server-1.1.0-SNAPSHOT.jar", "serve"])

Cursor / Windsurf

1. Open Settings > Features > MCP.
2. Click + Add New MCP Server.
3. Name: jvm-mcp
4. Type: command
5. Command: jvm-mcp serve

Once configured, ask your AI: “What Java processes are running?” or “Analyze the memory and detect deadlocks in PID 12345”.

---

CLI Usage

jvm-mcp doubles as a standalone diagnostic terminal CLI for local inspection:

# Verify local environment readiness and Attach API permissions
jvm-mcp doctor

# Discover running Java processes and frameworks
jvm-mcp list

# Inspect memory pools, GC pauses, and heap histogram
jvm-mcp memory 

# Diagnose thread states and detect deadlock cycles
jvm-mcp threads 

# Inspect Spring Boot ApplicationContext beans
jvm-mcp beans  --filter "*Service*"

# Introspect PostgreSQL schema and find missing indexes via JDBC
jvm-mcp pg --url "jdbc:postgresql://localhost:5432/mydb" --missing-indexes

# Query remote Spring Boot Actuator endpoints
jvm-mcp actuator --url "http://localhost:8080" --metrics

---

Exposed MCP Tools

The server exposes 14 diagnostic tools to AI assistants:

---

Architectural Principles

• Virtual Threads & Thread-Safe Stdio: Each incoming JSON-RPC request executes on a dedicated Java 21 Virtual Thread (Executors.newVirtualThreadPerTaskExecutor()). Outbound stdout writes are synchronized on a dedicated monitor lock to prevent frame interleaving.
• Dynamic JDK Management Agent: JMX access is initialized dynamically via VirtualMachine.startLocalManagementAgent(), falling back to standard $JAVA_HOME/lib/management-agent.jar. No custom agent bytecode is injected into target processes.
• Zero Runtime Framework Overhead: Operates with no heavy web or application frameworks (no Spring Boot runtime, Quarkus, Netty, Jackson, or reactive engines). It uses a lightweight custom JSON-RPC engine (SimpleJson), native JDK HttpClient, and Picocli for CLI execution, ensuring a cold start under 150ms.

---

Security & Defense Boundaries

1. OS Process Boundary & Privileged Access Control: Enforces numeric PID validation (> 0), process liveness checks, and OS user matching (ProcessHandle.info().user()). Cross-user attachment without operating system elevation is strictly rejected.
2. Automatic Sensitive Data Redaction: All diagnostic tool outputs and execution error messages returned over MCP are filtered through SensitiveDataRedactor to sanitize Bearer tokens, Basic credentials, passwords, API keys, embedded JDBC passwords, and JWTs.
3. Actuator SSRF & Path Traversal Mitigation: Enforces strict http/https scheme validation, disables HTTP redirect following (followRedirects: NEVER) to eliminate cloud metadata/internal network pivoting, and rejects directory traversal in endpoints.
4. PostgreSQL JDBC Hardening & Schema Validation: Enforces jdbc:postgresql:// protocol, validates loopback resolution, strips unsafe driver properties (socketFactory, sslrootcert, options), and validates schema names against standard SQL identifier patterns to prevent SQL injection.
5. Resource Bounding & Execution Timeouts: Heap histograms are bounded between 50 and 1,000 entries (capped at 100k lines), arguments are bounded via ToolArgs, and all tool invocations execute with an enforced 15-second virtual thread timeout.
6. ReDoS & Recursion Guards: Sanitizes glob wildcards in GlobMatcher to prevent quadratic backtracking and bounds SimpleJson recursion depth to 100.

---

Platform & Runtime Compatibility Matrix

---

Known Limitations and Trade-offs

• Container Boundaries: Direct host attachment across isolated Docker container namespaces fails due to separate PID and IPC namespaces. Attach from within the container namespace, use --pid=host, or use Actuator HTTP mode (jvm-mcp actuator --url ...).
• Virtual Threads Visibility (Project Loom): Current thread diagnostics leverage the standard JVM ThreadMXBean. In Java 21, unmounted virtual threads resting in continuation queues are not surfaced by ThreadMXBean. Comprehensive virtual thread inspection using HotSpot thread dumps / JVMTI is tracked under issue #10.
• Jlink / Jpackage Bundling: GraalVM Native Image was evaluated and rejected because jdk.attach dynamically loads HotSpot C++ native libraries (libattach.so / attach.dll), violating Closed-World AOT assumptions. We distribute minimal bundles containing a stripped modular JRE via jlink (Linux/macOS) and jpackage app images (Windows), maintaining cross-platform parity with startup times under 150ms.

---

Contributing & Governance

• ROADMAP.md: Milestones and active development phases.
• CONTRIBUTING.md: Local environment setup, module architecture, and guide for adding MCP tools.
• SECURITY.md: Vulnerability reporting policy and defense boundaries.
• CODE_OF_CONDUCT.md: Community standards (Contributor Covenant).

---

License

This project is licensed under the terms of the MIT License. See the LICENSE file for details.

Copyright © 2026 oscarbol09 / JVM-MCP Contributors.