jdi-mcp

A Model Context Protocol (MCP) server for JVM debugging using Java Debug Interface (JDI).

Features

• Full JDI Integration: Uses the high-level Java Debug Interface rather than raw JDWP protocol
• Breakpoint Management: Set, list, and clear breakpoints with deferred breakpoint support for unloaded classes
• Execution Control: Continue, pause, and step (over/into/out) through code
• Stack Inspection: View stack traces with local variables
• Expression Evaluation: Evaluate expressions including field access and method calls
• Thread Management: List and inspect all threads

Requirements

• JDK 21+
• Gradle 8+

Building

./gradlew build
./gradlew installDist

This creates the executable at ./build/install/jdi-mcp/bin/jdi-mcp.

Installation

Claude Code

Add via the CLI:

claude mcp add jdi-mcp /absolute/path/to/jdi-mcp/build/install/jdi-mcp/bin/jdi-mcp

Or manually add to ~/.claude.json:

{
  "mcpServers": {
    "jdi-mcp": {
      "command": "/absolute/path/to/jdi-mcp/build/install/jdi-mcp/bin/jdi-mcp"
    }
  }
}

For project-specific configuration, add to .mcp.json in your project root.

Claude Desktop

Add to your Claude Desktop config file:

Platform	Config Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "jdi-mcp": {
      "command": "/absolute/path/to/jdi-mcp/build/install/jdi-mcp/bin/jdi-mcp"
    }
  }
}

Important: After editing the config, completely quit Claude Desktop and restart it for changes to take effect.

Running Standalone

./gradlew run

The server communicates over STDIO using the MCP protocol.

Tools

Tool	Description
debug.attach	Connect to a JVM with JDWP agent
debug.disconnect	Disconnect from the JVM
debug.set_breakpoint	Set breakpoint at class:line
debug.list_breakpoints	List all breakpoints
debug.clear_breakpoint	Remove a breakpoint
debug.continue	Resume execution
debug.pause	Suspend execution
debug.step_over	Step over current line
debug.step_into	Step into method call
debug.step_out	Step out of method
debug.get_stack	Get stack trace with variables
debug.evaluate	Evaluate expression
debug.list_threads	List all threads
debug.get_last_event	Get last debug event

Usage Example

1. Start a JVM with debug agent:

   java -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005 -jar YourApp.jar
   

2. Connect using the MCP tools:

   debug.attach(port=5005)
   debug.set_breakpoint(class_name="com.example.Main", line=42)
   debug.continue()
   # ... breakpoint hit ...
   debug.get_stack(thread_id="main")
   debug.evaluate(thread_id="main", expression="this.value")
   debug.step_over(thread_id="main")
   

Testing with MCP Inspector

npx @modelcontextprotocol/inspector ./gradlew run

Expression Syntax

The debug.evaluate tool supports:

• Variable lookup: variableName
• this reference: this
• Field access: obj.field
• Method calls (no-arg): obj.method()
• Chaining: this.service.getName()

Troubleshooting

Verify Prerequisites

# Check JDK version (requires 21+)
java -version

# Check Gradle
./gradlew --version

Verify Installation

# Ensure the binary exists after building
ls -la ./build/install/jdi-mcp/bin/jdi-mcp

# Test with MCP Inspector
npx @modelcontextprotocol/inspector ./build/install/jdi-mcp/bin/jdi-mcp

Common Issues

• "Class not found" errors: Run ./gradlew installDist to create the distribution
• Server not responding: Ensure stdin stays open; the server exits on EOF
• Can't connect to JVM: Verify the target JVM is running with -agentlib:jdwp=transport=dt_socket,server=y,address=*:PORT
• Claude Desktop not seeing the server: Completely quit and restart Claude Desktop after config changes

License

MIT