jdb-mcp
v1.0.0
Published
An MCP server that turns an LLM into a Java debugger via JDI - pre-declare the values you want before a breakpoint fires and get back a compact structured snapshot, no heap dumps. Requires JDK 17+.
Maintainers
Readme
jdb-mcp - Let your LLM debug Java (JDB / JDI over MCP, for Claude Code & any MCP client)
jdb-mcp turns an LLM into a Java debugger. It exposes JDI - the engine behind jdb and
the JDWP protocol - as an MCP server, so AI agents like Claude Code can set
breakpoints, step through code, capture exceptions, and inspect a live JVM. The core advantage:
the AI pre-declares exactly which values it wants before the breakpoint fires, and jdb-mcp
returns only those as a compact structured snapshot - no heap dumps, no stack-dredging, no
context blowup.
Keywords:
LLM·AI agent·Java DEBUG·JDB·JDI·JDWP·MCP·Claude Code·breakpoint·live JVM inspection
Pre-declare your data, set one breakpoint, verify, stop. Anti-addiction built in - a session counter warns after 8+ debug actions, steering the AI toward logs/tests first.
Quick Start
# Requires JDK 17+ (none of the source - just install and go)
npm install -g jdb-mcp
# Or use without installing:
npx jdb-mcpSet JAVA_HOME if your JDK isn't on the PATH:
# Linux / macOS
export JAVA_HOME=/path/to/jdk-17
# Windows
set JAVA_HOME=F:\path\to\jdk-17Claude Code Wiring
{
"mcpServers": {
"jdb-mcp": {
"command": "npx",
"args": ["jdb-mcp"]
}
}
}Or if installed globally:
{
"mcpServers": {
"jdb-mcp": {
"command": "jdb-mcp"
}
}
}If your JDK isn't on the PATH, set it inline:
{
"mcpServers": {
"jdb-mcp": {
"command": "npx",
"args": ["jdb-mcp"],
"env": { "JAVA_HOME": "/path/to/jdk-17" }
}
}
}How It Works
- The
jdb-mcpcommand finds your JDK 17+ (JAVA_HOME->PATH-> common locations). - It launches the bundled JDI debug server over MCP stdio.
- The AI calls
start_session(jar="...")to launch your target, orstart_session(attach={host, port})to attach. - Set breakpoints with pre-declared captures, get snapshots, step through code, inspect exceptions.
Requirements
- JDK 17+ (any distribution: Eclipse Adoptium, Oracle, Microsoft, etc.)
- Node.js 16+ (just to run the wrapper script)
- No source code, no Maven, no build step - just
npm install
Tools
17 MCP tools: start_session, stop_session, configure, session_status,
list_debuggable_jvms, resolve_class, list_classes, set_breakpoint,
set_exception_breakpoint, list_hits, remove_breakpoint, resume,
get_frames, get_variables, step, explore, eval.
See the full README for the expression grammar, modes, limits, and safety policy.
License
MIT - the most permissive open-source license. Use it commercially, fork it, ship it, no strings attached. See LICENSE.
