{
  "markdown": "# MCP Server for JDB Java Debugging (karellen-jdb-mcp)\n\n[![Gitter](https://img.shields.io/gitter/room/karellen/lobby?logo=gitter)](https://gitter.im/karellen/Lobby)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/karellen/karellen-jdb-mcp/build.yml?branch=master)](https://github.com/karellen/karellen-jdb-mcp/actions/workflows/build.yml)\n[![Coverage Status](https://img.shields.io/coveralls/github/karellen/karellen-jdb-mcp/master?logo=coveralls)](https://coveralls.io/r/karellen/karellen-jdb-mcp?branch=master)\n\n[![karellen-jdb-mcp Version](https://img.shields.io/pypi/v/karellen-jdb-mcp?logo=pypi)](https://pypi.org/project/karellen-jdb-mcp/)\n[![karellen-jdb-mcp Python Versions](https://img.shields.io/pypi/pyversions/karellen-jdb-mcp?logo=pypi)](https://pypi.org/project/karellen-jdb-mcp/)\n[![karellen-jdb-mcp Downloads Per Day](https://img.shields.io/pypi/dd/karellen-jdb-mcp?logo=pypi)](https://pypi.org/project/karellen-jdb-mcp/)\n[![karellen-jdb-mcp Downloads Per Week](https://img.shields.io/pypi/dw/karellen-jdb-mcp?logo=pypi)](https://pypi.org/project/karellen-jdb-mcp/)\n[![karellen-jdb-mcp Downloads Per Month](https://img.shields.io/pypi/dm/karellen-jdb-mcp?logo=pypi)](https://pypi.org/project/karellen-jdb-mcp/)\n\n## Overview\n\n`karellen-jdb-mcp` is an [MCP](https://modelcontextprotocol.io/) (Model Context Protocol)\nserver that enables any MCP-compliant LLM client to use [JDB](https://docs.oracle.com/en/java/javase/21/docs/specs/man/jdb.html)\n(the Java Debugger) for debugging JVM processes. The LLM can attach to a running JVM,\nset breakpoints, step through code, evaluate expressions, inspect threads, and analyze\nconcurrency issues, all through structured JSON tool calls over the JDWP protocol.\n\n## Requirements\n\n- **Java Development Kit** (JDK) with `jdb` on PATH (JDK 8 through 24+ supported)\n- **Python** >= 3.10\n- Works on **Linux**, **macOS**, and **Windows** (anywhere JDB runs)\n\n### Installing a JDK\n\n**Fedora / RHEL / CentOS:**\n```bash\nsudo dnf install java-21-openjdk-devel\n```\n\n**Ubuntu / Debian:**\n```bash\nsudo apt install openjdk-21-jdk\n```\n\n**macOS (Homebrew):**\n```bash\nbrew install openjdk@21\n```\n\n### Verify the setup\n\n```bash\njdb -version\n```\n\nThis should print something like `This is jdb version 21.0.4`.\n\n## Installation\n\n```bash\npip install karellen-jdb-mcp\n```\n\nOr with pipx for an isolated environment:\n\n```bash\npipx install karellen-jdb-mcp\n```\n\n## Claude Code Integration\n\n### Claude Code plugin (recommended)\n\nThe plugin automatically configures the MCP server and includes:\n\n- **Exception detection hook** that suggests JDB when a Bash command output contains\n  Java exception stack traces (`Exception in thread`, `NullPointerException`, etc.)\n- **`/karellen-jdb-mcp:jdb-debug` skill** that walks through the full\n  launch-attach-debug workflow step by step, with build-tool-specific JDWP stanzas\n- **`jdb-investigator` agent** that Claude can spawn to autonomously investigate\n  Java exceptions, deadlocks, and logic bugs using JDB\n\nFrom the [Karellen plugins marketplace](https://github.com/karellen/claude-plugins):\n\n```bash\nclaude plugin marketplace add karellen/claude-plugins\nclaude plugin install karellen-jdb-mcp@karellen-plugins\n```\n\nOr from the official Anthropic marketplace (if accepted):\n\n```bash\nclaude plugin install karellen-jdb-mcp@claude-plugins-official\n```\n\nOr load directly from a local checkout for testing:\n\n```bash\nclaude --plugin-dir /path/to/karellen-jdb-mcp\n```\n\n### Manual MCP server configuration\n\nIf you prefer not to use the plugin, you can configure the MCP server directly.\nThis gives you the MCP tools but not the skill, agent, or exception detection hook.\n\nUsing the CLI:\n\n```bash\nclaude mcp add --transport stdio karellen-jdb-mcp -- karellen-jdb-mcp\n```\n\nOr manually add to `~/.claude.json` (user scope) or `.mcp.json` in your project root\n(project scope, shared via version control):\n\n```json\n{\n  \"mcpServers\": {\n    \"karellen-jdb-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"karellen-jdb-mcp\"\n    }\n  }\n}\n```\n\nIf installed with pipx:\n\n```bash\nclaude mcp add --transport stdio karellen-jdb-mcp -- pipx run karellen-jdb-mcp\n```\n\nor manually:\n\n```json\n{\n  \"mcpServers\": {\n    \"karellen-jdb-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"pipx\",\n      \"args\": [\"run\", \"karellen-jdb-mcp\"]\n    }\n  }\n}\n```\n\n### Auto-approve jdb tools\n\nBy default Claude Code will prompt for confirmation before each `jdb_*` tool call.\nYou can approve individually by selecting \"Yes, and don't ask again\" when prompted.\n\nTo auto-approve all tools upfront, add a permission rule to your user settings\n(`~/.claude/settings.json`):\n\n```json\n{\n  \"permissions\": {\n    \"allow\": [\n      \"mcp__plugin_karellen-jdb-mcp_karellen-jdb-mcp__*\",\n      \"mcp__karellen-jdb-mcp__*\"\n    ]\n  }\n}\n```\n\nThe first rule covers plugin-loaded tools, the second covers manual MCP configuration.\n\nOr for a project-scoped setting, add the same rule to `.claude/settings.json` in your\nproject root (this file can be committed to version control so all team members get it).\n\n## Quick Start\n\n### With `jdb_launch` (recommended)\n\nLaunch the JVM with `${JDB_PORT}` substitution — a random free port is allocated:\n\n```\njdb_launch([\"java\", \"-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:${JDB_PORT}\",\n            \"-cp\", \"target/classes\", \"com.example.Main\"])\n```\n\nConnect (port auto-resolves when there's one launched process):\n\n```\njdb_connect(wait_timeout=30)\n```\n\nDebug:\n\n```\njdb_breakpoint_set(\"com.example.Main:42\")\njdb_run()\njdb_where()\njdb_locals()\n```\n\nClean up:\n\n```\njdb_disconnect()\njdb_launch_stop(port=<port>)\n```\n\n### With a manually started JVM\n\nStart the JVM yourself with JDWP on a known port, then connect:\n\n```\njdb_connect(port=5005, wait_timeout=30)\n```\n\n## Available Tools\n\n### Process Launch\n| Tool | Description |\n|------|-------------|\n| `jdb_launch` | Launch a JVM with JDWP on a random port. `${JDB_PORT}` is substituted in the command. |\n| `jdb_launch_list` | List all launched JVM processes with status. |\n| `jdb_launch_status` | Get status of a launched process by port. |\n| `jdb_launch_stop` | Stop a launched process by port. |\n\n### Session Lifecycle\n| Tool | Description |\n|------|-------------|\n| `jdb_connect` | Attach to a running JVM via JDWP. Auto-resolves port from single launched process, or defaults to 5005. |\n| `jdb_disconnect` | Disconnect and clean up. Port optional if only one session active. |\n| `jdb_session_list` | List all active debug sessions with port, connection status, and JDK version. |\n| `jdb_version` | Get JDB version info and available features. |\n\n### Execution Control\n| Tool | Description |\n|------|-------------|\n| `jdb_run` | Start execution of the application's main class. Returns immediately once execution resumes. |\n| `jdb_cont` | Continue execution. Returns immediately once the JVM resumes (fire-and-forget). Returns stop event if a breakpoint/exception is hit within `TIMEOUT_RESUME`. |\n| `jdb_step` | Step into (enter method calls). Returns stop event on completion or returns immediately if execution resumes. |\n| `jdb_next` | Step over (skip method calls). Same return behavior as step. |\n| `jdb_step_up` | Step out (run until current method returns). Same return behavior as step. |\n| `jdb_wait_for_event` | Wait for a stop event after `jdb_cont`/`jdb_run` returned `reason=\"resumed\"`. Blocks until breakpoint/exception/exit or timeout (default 120s). |\n\n### Breakpoints\n| Tool | Description |\n|------|-------------|\n| `jdb_breakpoint_set` | Set breakpoint at class:line or class.method. Supports thread filters and suspend policy on JDK 13+. |\n| `jdb_breakpoint_clear` | Clear a breakpoint. |\n| `jdb_breakpoint_list` | List all breakpoints. |\n| `jdb_catch` | Break on exception (caught/uncaught/all). Supports wildcard patterns. |\n| `jdb_ignore` | Cancel an exception breakpoint. |\n\n### Watchpoints\n| Tool | Description |\n|------|-------------|\n| `jdb_watch` | Watch field access/modifications. |\n| `jdb_unwatch` | Remove a field watchpoint. |\n\n### Thread Management\n| Tool | Description |\n|------|-------------|\n| `jdb_threads` | List all threads by group with status. |\n| `jdb_thread` | Set default thread for subsequent commands. |\n| `jdb_suspend` | Suspend threads (all or specific). |\n| `jdb_resume` | Resume threads (all or specific). |\n\n### Stack Navigation\n| Tool | Description |\n|------|-------------|\n| `jdb_where` | Get call stack (stack trace). Use `\"all\"` for all threads. |\n| `jdb_up` | Move up the call stack (toward caller). |\n| `jdb_down` | Move down the call stack (toward callee). |\n\n### State Inspection\n| Tool | Description |\n|------|-------------|\n| `jdb_print` | Evaluate Java expression (fields, locals, method calls, arithmetic). |\n| `jdb_dump` | Dump object showing all fields (static and instance). |\n| `jdb_eval` | Evaluate expression (alias for print). |\n| `jdb_set` | Assign value to variable, field, or array element. |\n| `jdb_locals` | List local variables with values. |\n\n### Class Introspection\n| Tool | Description |\n|------|-------------|\n| `jdb_classes` | List all loaded classes. |\n| `jdb_class_info` | Show class details (superclass, interfaces). |\n| `jdb_methods` | List class methods. |\n| `jdb_fields` | List class fields. |\n\n### Source\n| Tool | Description |\n|------|-------------|\n| `jdb_list` | List source code at current position or specified location. |\n| `jdb_sourcepath` | Display or change source path for .java files. |\n| `jdb_classpath` | Print classpath info from target JVM. |\n\n### Concurrency Analysis\n| Tool | Description |\n|------|-------------|\n| `jdb_lock` | Object lock/monitor info (owner thread, waiting threads). |\n| `jdb_threadlocks` | Thread lock info (owned monitors, lock being waited on). |\n\n### Frame Manipulation\n| Tool | Description |\n|------|-------------|\n| `jdb_pop` | Pop current frame (return to caller, allows re-execution). |\n| `jdb_reenter` | Re-enter current method from the beginning. |\n\n### Tracing\n| Tool | Description |\n|------|-------------|\n| `jdb_trace` | Trace method entries/exits (optionally per-thread). |\n| `jdb_untrace` | Stop tracing. |\n\n### Monitors (Auto-execute)\n| Tool | Description |\n|------|-------------|\n| `jdb_monitor` | Auto-execute a command on every stop (e.g. `\"locals\"`, `\"where\"`). |\n| `jdb_monitor_list` | List active monitors. |\n| `jdb_unmonitor` | Remove a monitor. |\n\n### Configuration\n| Tool | Description |\n|------|-------------|\n| `jdb_exclude` | Set/display step exclusion filter (skip library classes when stepping). |\n\n**Note:** All debugging tools accept an optional `port` parameter. When only one session\nis active, it auto-resolves. When multiple sessions are active, `port` is required.\n\n## Configuration\n\n### Timeouts\n\nAll timeouts are configurable via environment variables (in seconds). Set them in your\nMCP server configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"karellen-jdb-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"karellen-jdb-mcp\",\n      \"env\": {\n        \"JDB_MCP_TIMEOUT_EXECUTION\": \"300\"\n      }\n    }\n  }\n}\n```\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `JDB_MCP_TIMEOUT_CONNECT` | 60 | JDB attach and initial prompt |\n| `JDB_MCP_TIMEOUT_COMMAND` | 30 | Non-execution commands (breakpoints, inspection, etc.) |\n| `JDB_MCP_TIMEOUT_EXECUTION` | 120 | Prompt-based commands (used internally by `send_command`) |\n| `JDB_MCP_TIMEOUT_RESUME` | 5 | Execution commands (run, cont, step, next, step up). These return immediately when output arrives or after this timeout if execution resumes with no output (fire-and-forget). |\n\n## Build Tool Debug Stanzas\n\nTo debug a JVM process, it must be started with the JDWP agent. The exact syntax\nvaries by build tool:\n\n| Build Tool | Command |\n|---|---|\n| Plain `java` | `java -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005 ...` |\n| Maven Surefire | `mvn -Dmaven.surefire.debug test` |\n| Maven Failsafe | `mvn -Dmaven.failsafe.debug verify` |\n| Gradle tests | `./gradlew test --debug-jvm` |\n| Tycho Surefire | `mvn verify -Dtycho.testArgLine=\"-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005\"` |\n| Spring Boot | `mvn spring-boot:run -Dspring-boot.run.jvmArguments=\"-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005\"` |\n| Any (fallback) | `JAVA_TOOL_OPTIONS=\"-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005\" <command>` |\n\n## License\n\nApache-2.0\n\n## Privacy\n\nSee [PRIVACY.md](PRIVACY.md). This software does not collect or transmit any data.\n",
  "bytes": 12486,
  "sha": "4d78c7726ff15004a903d8ebcf102a1a64b2f5560fee803e5eebb94f205f5eb0",
  "repo_slug": "karellen/karellen-jdb-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_karellen_karellen_jdb_mcp_karellen_jdb_m_471e8fa0/readme"
}