jdwp-mcp
Provides deployment configuration for debugging Java applications running in Docker containers, enabling JDWP connections to containerized JVMs
Supports debugging of Java applications built with Gradle, including deployment guidance and configuration for Gradle-based project setups
Enables debugging of Hibernate ORM usage within Java applications, including inspection of SQL generation and diagnosis of ORM-related issues in complex framework stacks
Supports remote debugging of Java workloads deployed in Kubernetes clusters via kubectl port-forward, allowing attachment to JVMs in containerized orchestration environments
Supports debugging of applications built with the Spring framework, including navigation of deep Spring stacks and inspection of framework-managed components and dependency injection
Enables debugging of Spring Boot specific features and auto-configuration issues, including investigation of ObservationRegistry and other Boot-specific runtime behavior
jdwp-mcp
Debug live JVMs through JDWP — from any MCP-compatible agent.
Attach to a running Java process, pause threads, inspect stacks and objects, set breakpoints, and evaluate state — through natural language. One prompt starts an agent-driven diagnosis loop with live runtime data.
Works with Claude Code, Codex, Cursor, or any MCP-compatible agent.
See it in action
A service query is hanging. Find the root cause:
> Attach to localhost:5005 and find out why a query is stuck.The agent attaches, pauses all threads, and scans for the problem:
connected localhost:5005
paused
24 threads, 2 blocked
Thread pool-3-thread-7 is waiting for a monitor lock:
#0 RolapResult.loadMembers:142
monitor=@3f2a state=BLOCKED
#1 RolapResult.execute:89
Lock is held by pool-3-thread-2, which is running:
#0 SqlStatement.execute:218
sql="SELECT ... FROM fact_table" -- full scan on 36M rows
Root cause: the query bypassed the aggregate table and fell back to
a full fact-table scan. Thread-7 is waiting for thread-2 to finish.One prompt. Six tool calls. Lock contention and root cause identified.
Related MCP server: karellen-jdb-mcp
Quick Start
1. Install
pip install jdwp-mcp# Pre-built binary
curl -fsSL https://raw.githubusercontent.com/dronsv/jdwp-mcp/main/install.sh | sh
# Cargo (requires Rust)
cargo install --git https://github.com/dronsv/jdwp-mcp
# From source
git clone https://github.com/dronsv/jdwp-mcp && cd jdwp-mcp && cargo build --release2. Configure your agent
claude mcp add jdwp jdwp-mcpFor Codex, Cursor, or other MCP-compatible agents, add to .mcp.json:
{
"mcpServers": {
"jdwp": {
"command": "jdwp-mcp"
}
}
}3. Start your Java app with JDWP
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar app.jar4. Debug
Attach to localhost:5005 and set a breakpoint at com.example.MyService line 425. Auto-approve (optional)
Debugging involves many rapid tool calls. Auto-approve eliminates confirm prompts:
# Allow all jdwp tools for this project
claude config set --project allowedTools 'mcp__jdwp__*'claude config set allowedTools 'mcp__jdwp__*'Only enable for projects you trust — jdwp tools can pause threads, modify variables, and invoke methods on the target JVM.
Prompt packs
Pick the pack that matches your situation:
App hangs or is slow
Attach to localhost:5005
Pause the JVM and find all blocked or waiting threads
Show the stack for the blocked thread with variables
Who holds the lock? Show their stack tooException in logs
Attach to localhost:5005
Set an exception breakpoint for NullPointerException
Wait for the exception to fire
Show the stack and all local variables at the throw siteNeed to understand a code path
Attach to localhost:5005
Trace method calls on com.example.service
[send your HTTP request]
Show the trace result — which methods were called?Breakpoint-driven debugging
Attach to localhost:5005
Find classes matching UserService
List methods of UserService with line numbers
Set a breakpoint at UserService line 45
When it hits, show the stack with all variables
Step over to the next lineClaude Code commands
If you clone this repo, you get ready-made slash commands:
/investigate-hang— diagnose a hanging JVM (pause, find blocked threads, trace locks)/investigate-exception— catch a live exception and inspect the throw site/trace-request— trace which methods a request passes through
And an autonomous investigator agent (.claude/agents/jdwp-investigator.md) that can be spawned to diagnose hangs, deadlocks, exceptions, and unexpected code paths.
See .claude/settings.example.json for recommended auto-approve and update-check config.
Best first use cases
Hung requests and deadlocks
Blocked thread pools
Suspicious SQL or runtime state mismatch
Breakpoint-driven diagnosis without IDE access
Remote debugging via
kubectl port-forward
Why this instead of jstack or an IDE?
Works inside your agent — no tool switching, no separate debugger window
Combines attach + inspect + reasoning in one loop — the agent decides what to look at next
Conversational — describe the problem, the agent runs the debug session
Ground truth for large codebases — in complex projects with deep framework stacks (Spring, Hibernate, OLAP engines), agents can get lost tracing code paths statically. Live debugging gives the agent actual runtime state: which thread holds the lock, what SQL was generated, what value a variable actually has right now
Tools
Connection and control attach, disconnect, pause, continue, step into/over/out
Breakpoints and events set_breakpoint (with conditions), clear, list, exception_breakpoint, watch (field modification), wait_for_event
Inspection get_stack (auto-resolves objects), get_variable, inspect, eval, set_value, snapshot, find_class, list_methods, list_threads, vm_info
Tracing trace (arm method-level tracing on a package), trace_result (get the call path)
Don't use it for
Postmortem heap analysis
Always-on production observability
Environments where JDWP attach or thread pausing is operationally unsafe
Operational note
JDWP changes runtime behavior. Pausing threads and setting breakpoints may be disruptive. Use carefully in production; prefer staging environments or controlled maintenance windows.
Deploy scenarios
See docs/deploy.md for setup with Maven, Gradle, Tomcat, Docker, Kubernetes (port-forward), and SSH tunnels.
Examples
Debugging a hanging query — full walkthrough: lock contention, thread analysis, root cause identification
Observability debugging — investigating Spring Boot ObservationRegistry issues
Architecture
Agent --> MCP Server --> JDWP Client --> TCP --> JVM
|
Translates tool calls to JDWP,
tracks session state, summarizes
runtime objects for the agent.Building from source
cargo build --release
cargo testLicense
MIT
Available Tools
28 toolsdebug.attachC
Connect to JVM via JDWP
Inputs: host (required), port (required), allow_remote, timeout_ms.
debug.clear_breakpointB
Remove a breakpoint by ID
Inputs: breakpoint_id (required).
debug.continueA
Resume all threads
Inputs: no named parameters.
debug.disconnectA
End debug session
Inputs: no named parameters.
debug.evalC
Invoke a method on an object. Supports args: list.get(0), map.get("key")
Inputs: object_id (required), args, method, thread_id.
debug.exception_breakpointA
Break on exceptions (caught/uncaught, optionally by class)
Inputs: caught, class_pattern, uncaught.
debug.find_classB
Search loaded classes by name pattern
Inputs: pattern (required).
debug.get_last_eventB
Show last breakpoint/step event
Inputs: no named parameters.
debug.get_stackC
Get stack frames with variables
Inputs: include_variables, max_frames, max_variable_depth, thread_id.
debug.get_variableB
Read one local variable by name
Inputs: name (required), frame_index, thread_id.
debug.inspectB
Inspect object fields by object ID
Inputs: object_id (required).
debug.list_breakpointsB
List active breakpoints
Inputs: no named parameters.
debug.list_methodsB
List methods of a class with line ranges
Inputs: class_pattern (required).
debug.list_threadsB
List all threads
Inputs: no named parameters.
debug.pauseB
Suspend all threads
Inputs: no named parameters.
debug.select_threadB
Set default thread for inspection
Inputs: thread_id (required).
debug.set_breakpointB
Set breakpoint at class:line, optionally conditional
Inputs: class_pattern (required), line (required), condition, method.
debug.set_valueB
Set a local variable value in a stack frame
Inputs: name (required), value (required), frame_index, thread_id.
debug.snapshotA
Combined dump: last event + breakpoints + stack with vars
Inputs: no named parameters.
debug.step_intoB
Step into next line
Inputs: thread_id.
debug.step_outC
Step out of current frame
Inputs: thread_id.
debug.step_overB
Step over next line
Inputs: thread_id.
debug.traceA
Trace method calls on a class/package. Returns immediately; use debug.trace_result to get the call path.
Inputs: class_pattern (required), aggregate, include_args.
debug.trace_resultA
Get collected trace after debug.trace. Shows call path with depth.
Inputs: clear, min_ms.
debug.vm_infoA
Get JVM version info
Inputs: no named parameters.
debug.wait_for_classA
Wait for a class to be loaded by the JVM. Use when set_breakpoint says class not found.
Inputs: class_pattern (required), timeout_ms.
debug.wait_for_eventC
Wait for next event with timeout
Inputs: timeout_ms.
debug.watchB
Watchpoint: break when a field is modified
Inputs: class_pattern (required), field (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Each tool has a clearly distinct purpose, covering breakpoints, stepping, variable inspection, evaluation, tracing, and thread control. No two tools have overlapping functionality that would cause confusion.
All tools use the 'debug.' prefix and follow a consistent verb_noun or action_noun pattern in lowercase with underscores. Verbs like get, set, list, clear, step, wait are used uniformly.
With 28 tools, the count is slightly above the typical 3-15 range but still reasonable for a comprehensive JDWP debugger covering many operations. The tools are not redundant.
The tool surface covers major debugging workflows: attach, breakpoints, stepping, variable inspection, evaluation, tracing, and thread management. Minor gaps like modifying object fields or 'run to cursor' are absent but workable.
Maintenance
Related MCP Connectors
Live browser debugging for AI assistants — DOM, console, network via MCP.
Ship better Java with your coding agent.
Build, run, inspect, and continue AgentScript workflows on connected Super Chrome and Mac clients.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Related MCP Servers
- AlicenseAqualityAmaintenanceEnables AI agents to perform step-through debugging of Python, JavaScript/Node.js, and Rust programs using the Debug Adapter Protocol, with support for breakpoints, variable inspection, and stack traces.29193MIT

karellen-jdb-mcpofficial
AlicenseNot gradedqualityBmaintenanceEnables LLMs to debug Java applications using JDB, supporting breakpoints, stepping, expression evaluation, thread analysis, and more.4Apache 2.0- FlicenseNot gradedqualityBmaintenanceBridges agentic coding tools and live Java runtime behavior through a lightweight sidecar agent. Attaches directly to a running JVM to provide bytecode-level runtime signals for probe-verified inspection and deterministic debugging.2-
- AlicenseNot gradedqualityDmaintenanceBridges AI agents with VS Code's debugger, enabling breakpoint management, step execution, variable inspection, and stack tracing via CLI commands.25GPL 3.0