jetbrains-debugger

JetBrains Debugger MCP

Use these tools to actually debug applications in a JetBrains IDE rather than guessing from static code.

Complete parameter reference: See references/tool-reference.md for all tool parameters, types, defaults, and return schemas.

When to Use the Debugger

USE the debugger when:

• A bug involves runtime state (wrong values, unexpected nulls, incorrect flow)
• Reading code alone doesn't explain the behavior
• The user asks "why does X happen" or "what value does Y have"
• A test fails and the cause isn't obvious from the assertion message
• You need to verify a hypothesis about execution flow
• The user explicitly asks to debug

DON'T use the debugger when:

• The bug is a clear syntax error, typo, or missing import
• The fix is obvious from reading the code (e.g., off-by-one, wrong operator)
• There's no run configuration available to debug

Core Workflow

Standard Debugging Sequence

1. list_run_configurations          -- Find a config with can_debug: true
2. set_breakpoint                   -- Set breakpoint(s) BEFORE starting
3. start_debug_session              -- Launch the debugger
4. wait_for_pause(timeout=60)       -- Block until breakpoint hit (returns full status)
5. evaluate_expression              -- Test hypotheses about values
6. step_over / step_into / step_out -- Navigate through code
7. wait_for_pause(timeout=10)       -- Wait for step to complete, get state
8. resume_execution                 -- Continue to next breakpoint
9. wait_for_pause(timeout=60)       -- Block until next breakpoint hit
10. stop_debug_session              -- Clean up when done

Critical Rules

1. Set breakpoints BEFORE starting the session. Breakpoints can be set without an active session. Setting them first ensures the program pauses where you need it.

2. After resume_execution or any step command, use wait_for_pause to block until the session pauses. It returns the full session status (variables, stack, source, location) when the pause occurs — no polling needed. Step/resume commands return immediately with newState: "running" and do NOT wait for the program to pause.