MCP Server for JDB Java Debugging (karellen-jdb-mcp)

Overview

karellen-jdb-mcp is an MCP (Model Context Protocol) server that enables any MCP-compliant LLM client to use JDB (the Java Debugger) for debugging JVM processes. The LLM can attach to a running JVM, set breakpoints, step through code, evaluate expressions, inspect threads, and analyze concurrency issues, all through structured JSON tool calls over the JDWP protocol.

Requirements

• Java Development Kit (JDK) with jdb on PATH (JDK 8 through 24+ supported)
• Python >= 3.10
• Works on Linux, macOS, and Windows (anywhere JDB runs)

Installing a JDK

Fedora / RHEL / CentOS:

sudo dnf install java-21-openjdk-devel

Ubuntu / Debian:

sudo apt install openjdk-21-jdk

macOS (Homebrew):

brew install openjdk@21

Verify the setup

jdb -version

This should print something like This is jdb version 21.0.4.

Installation

pip install karellen-jdb-mcp

Or with pipx for an isolated environment:

pipx install karellen-jdb-mcp

Claude Code Integration

Claude Code plugin (recommended)

The plugin automatically configures the MCP server and includes:

• Exception detection hook that suggests JDB when a Bash command output contains

Java exception stack traces (Exception in thread, NullPointerException, etc.)

• `/karellen-jdb-mcp:jdb-debug` skill that walks through the full

launch-attach-debug workflow step by step, with build-tool-specific JDWP stanzas

• `jdb-investigator` agent that Claude can spawn to autonomously investigate

Java exceptions, deadlocks, and logic bugs using JDB

From the Karellen plugins marketplace:

claude plugin marketplace add karellen/claude-plugins
claude plugin install karellen-jdb-mcp@karellen-plugins

Or from the official Anthropic marketplace (if accepted):

claude plugin install karellen-jdb-mcp@claude-plugins-official

Or load directly from a local checkout for testing:

claude --plugin-dir /path/to/karellen-jdb-mcp

Manual MCP server configuration

If you prefer not to use the plugin, you can configure the MCP server directly. This gives you the MCP tools but not the skill, agent, or exception detection hook.

Using the CLI:

claude mcp add --transport stdio karellen-jdb-mcp -- karellen-jdb-mcp

Or manually add to ~/.claude.json (user scope) or .mcp.json in your project root (project scope, shared via version control):

{
  "mcpServers": {
    "karellen-jdb-mcp": {
      "type": "stdio",
      "command": "karellen-jdb-mcp"
    }
  }
}

If installed with pipx:

claude mcp add --transport stdio karellen-jdb-mcp -- pipx run karellen-jdb-mcp

or manually:

{
  "mcpServers": {
    "karellen-jdb-mcp": {
      "type": "stdio",
      "command": "pipx",
      "args": ["run", "karellen-jdb-mcp"]
    }
  }
}

Auto-approve jdb tools

By default Claude Code will prompt for confirmation before each jdb_* tool call. You can approve individually by selecting "Yes, and don't ask again" when prompted.

To auto-approve all tools upfront, add a permission rule to your user settings (~/.claude/settings.json):

{
  "permissions": {
    "allow": [
      "mcp__plugin_karellen-jdb-mcp_karellen-jdb-mcp__*",
      "mcp__karellen-jdb-mcp__*"
    ]
  }
}

The first rule covers plugin-loaded tools, the second covers manual MCP configuration.

Or for a project-scoped setting, add the same rule to .claude/settings.json in your project root (this file can be committed to version control so all team members get it).

Quick Start

With jdb_launch (recommended)

Launch the JVM with ${JDB_PORT} substitution — a random free port is allocated:

jdb_launch(["java", "-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:${JDB_PORT}",
            "-cp", "target/classes", "com.example.Main"])

Connect (port auto-resolves when there's one launched process):

jdb_connect(wait_timeout=30)

Debug:

jdb_breakpoint_set("com.example.Main:42")
jdb_run()
jdb_where()
jdb_locals()

Clean up:

jdb_disconnect()
jdb_launch_stop(port=<port>)

With a manually started JVM

Start the JVM yourself with JDWP on a known port, then connect:

jdb_connect(port=5005, wait_timeout=30)

Available Tools

Process Launch

Session Lifecycle

Execution Control

Breakpoints

Watchpoints

Thread Management

Stack Navigation

State Inspection

Class Introspection

Source

Concurrency Analysis

Frame Manipulation

Tracing

Monitors (Auto-execute)

Configuration

Note: All debugging tools accept an optional port parameter. When only one session is active, it auto-resolves. When multiple sessions are active, port is required.

Configuration

Timeouts

All timeouts are configurable via environment variables (in seconds). Set them in your MCP server configuration:

{
  "mcpServers": {
    "karellen-jdb-mcp": {
      "type": "stdio",
      "command": "karellen-jdb-mcp",
      "env": {
        "JDB_MCP_TIMEOUT_EXECUTION": "300"
      }
    }
  }
}

Build Tool Debug Stanzas

To debug a JVM process, it must be started with the JDWP agent. The exact syntax varies by build tool:

License

Apache-2.0

Privacy

See PRIVACY.md. This software does not collect or transmit any data.