karellen-jdb-mcp

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.