Skip to main content
Glama
jdwp-mcp
by dronsv

jdwp-mcp

Debug live JVMs through JDWP — from any MCP-compatible agent.

License: MIT

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 --release

2. Configure your agent

claude mcp add jdwp jdwp-mcp

For 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.jar

4. Debug

Attach to localhost:5005 and set a breakpoint at com.example.MyService line 42

5. 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 too

Exception 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 site

Need 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 line

Claude 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

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 test

License

MIT

Available Tools

28 tools
debug.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

    B3.4/5.0

    Scored across 28 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      Enables 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.
      29
      193
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables LLMs to debug Java applications using JDB, supporting breakpoints, stepping, expression evaluation, thread analysis, and more.
      4
      Apache 2.0
    • F
      license
      Not graded
      quality
      B
      maintenance
      Bridges 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
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Bridges AI agents with VS Code's debugger, enabling breakpoint management, step execution, variable inspection, and stack tracing via CLI commands.
      25
      GPL 3.0