Debugger MCP Server

1# Debugger MCP Server
2 
3![Build](https://github.com/hechtcarmel/jetbrains-debugger-mcp-plugin/workflows/Build/badge.svg)
4[![Version](https://img.shields.io/jetbrains/plugin/v/29233.svg)](https://plugins.jetbrains.com/plugin/29233)
5[![Downloads](https://img.shields.io/jetbrains/plugin/d/29233.svg)](https://plugins.jetbrains.com/plugin/29233)
6 
7A JetBrains IDE plugin that exposes an **MCP (Model Context Protocol) server**, giving AI coding assistants full programmatic control over the debugger. Set breakpoints, step through code, inspect variables, and evaluate expressions—all driven autonomously by your AI assistant.
8 
9**Fully tested**: IntelliJ IDEA, PyCharm, WebStorm, GoLand, RustRover, Android Studio, PhpStorm
10**May work** (untested): RubyMine, CLion, DataGrip
11 
12[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/hechtcarmel)
13 
14<!-- Plugin description -->
15**Debugger MCP Server** gives AI coding assistants complete control over the IDE's debugger through the Model Context Protocol (MCP). Let your AI assistant debug code autonomously—from setting breakpoints to inspecting variables to stepping through execution.
16 
17### Features
18 
19**Debug Session Management**
20- **Start/Stop Sessions** - Launch any run configuration in debug mode
21- **Rich Status** - Get comprehensive state in a single call (variables, stack, source context)
22- **Multi-Session Support** - Manage multiple concurrent debug sessions
23 
24**Breakpoint Management**
25- **Line Breakpoints** - Set breakpoints at any valid location
26- **Conditional Breakpoints** - Add conditions that must be true to pause
27- **Tracepoints** - Log messages without pausing execution
28 
29**Execution Control**
30- **Step Over/Into/Out** - Navigate through code line by line
31- **Resume & Pause** - Control execution flow
32- **Run to Line** - Continue execution until a specific line
33 
34**Variable Inspection**
35- **View Variables** - Inspect local variables, arguments, and object fields
36- **Modify Values** - Change variable values during debugging
37 
38**Expression Evaluation**
39- **Evaluate Expressions** - Run arbitrary expressions in the current context
40- **Code Fragments** - Execute multi-line code snippets
41 
42**Stack & Thread Navigation**
43- **Stack Traces** - View the complete call stack with source locations
44- **Frame Selection** - Switch context to any stack frame
45- **Thread Listing** - See all threads and their states
46 
47### Why Use This Plugin?
48 
49Unlike manual debugging, this plugin enables:
50- **Autonomous AI Debugging** - Your AI assistant can debug code without human intervention
51- **Rich Context in Single Calls** - Get variables, stack, and source in one request
52- **Programmatic Breakpoint Control** - Set conditional breakpoints with complex expressions
53- **Cross-IDE Compatibility** - Works with any JetBrains IDE that supports XDebugger
54- **22 Comprehensive Tools** - Full debugging capability through MCP
55 
56Perfect for AI-assisted development workflows where you want your assistant to investigate bugs, validate fixes, or explore code behavior autonomously.
57<!-- Plugin description end -->
58 
59## Table of Contents
60 
61- [Installation](#installation)
62- [Quick Start](#quick-start)
63- [Client Configuration](#client-configuration)
64- [Available Tools](#available-tools)
65- [Multi-Project Support](#multi-project-support)
66- [Tool Window](#tool-window)
67- [Error Codes](#error-codes)
68- [Settings](#settings)
69- [Requirements](#requirements)
70- [Contributing](#contributing)
71 
72## Installation
73 
74### Using the IDE built-in plugin system
75 
76<kbd>Settings/Preferences</kbd> > <kbd>Plugins</kbd> > <kbd>Marketplace</kbd> > <kbd>Search for "Debugger MCP Server"</kbd> > <kbd>Install</kbd>
77 
78### Using JetBrains Marketplace
79 
80Go to [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/29233) and install it by clicking the <kbd>Install to ...</kbd> button.
81 
82### Manual Installation
83 
84Download the [latest release](https://github.com/hechtcarmel/jetbrains-debugger-mcp-plugin/releases/latest) and install it manually:
85<kbd>Settings/Preferences</kbd> > <kbd>Plugins</kbd> > <kbd>⚙️</kbd> > <kbd>Install plugin from disk...</kbd>
86 
87## Quick Start
88 
891. **Install the plugin** and restart your JetBrains IDE
902. **Open a project** - the MCP server starts automatically
913. **Find your IDE port**: <kbd>Settings</kbd> > <kbd>Build, Execution, Deployment</kbd> > <kbd>Debugger</kbd> > <kbd>Built-in Server Port</kbd> (default: 63342)
924. **Configure your AI assistant** with the server URL: `http://127.0.0.1:{PORT}/debugger-mcp/sse`
935. **Use the tool window** (bottom panel: "Debugger MCP Server") to copy configuration or monitor commands
94 
95### Using the "Install on Coding Agents" Button
96 
97The easiest way to configure your AI assistant:
981. Open the "Debugger MCP Server" tool window (bottom panel)
992. Click the prominent **"Install on Coding Agents"** button on the right side of the toolbar
1003. A popup appears with two sections:
101   - **Install Now** - For Claude Code CLI and Codex CLI: Runs the installation command automatically
102   - **Copy Configuration** - For other clients: Copies the JSON config to your clipboard
1034. For "Copy Configuration" clients, paste the config into the appropriate config file
104 
105## Example Workflow
106 
107Just tell your AI assistant:
108 
109> "Debug the calculateTotal function—set a breakpoint at line 42, run the tests in debug mode, and show me the variable values when it pauses."
110 
111Or for more complex debugging:
112 
113> "There's a bug in UserService. Set a breakpoint at line 42, run the tests in debug mode, and when it breaks, show me the stack trace and all local variables."
114 
115## Client Configuration
116 
117### Claude Code (CLI)
118 
119The easiest way is to use the **"Install on Coding Agents"** button in the IDE's tool window—it generates the correct command with your IDE-specific server name (e.g., `intellij-debugger`, `pycharm-debugger`).
120 
121Or run this command manually in your terminal (replace `<ide>-debugger` with your IDE name):
122 
123```bash
124claude mcp add --transport sse intellij-debugger http://127.0.0.1:63342/debugger-mcp/sse --scope user
125```
126 
127**IDE-specific server names:**
128- IntelliJ IDEA: `intellij-debugger`
129- PyCharm: `pycharm-debugger`
130- WebStorm: `webstorm-debugger`
131- GoLand: `goland-debugger`
132- PhpStorm: `phpstorm-debugger`
133- RubyMine: `rubymine-debugger`
134- CLion: `clion-debugger`
135- RustRover: `rustrover-debugger`
136- Android Studio: `android-studio-debugger`
137 
138Options:
139- `--scope user` - Adds globally for all projects
140- `--scope project` - Adds to current project only
141 
142To remove: `claude mcp remove intellij-debugger` (use your IDE's name)
143 
144### Codex CLI
145 
146The easiest way is to use the **"Install on Coding Agents"** button in the IDE's tool window—it generates the correct command with your IDE-specific server name (e.g., `intellij-debugger`, `pycharm-debugger`).
147 
148Or run this command manually in your terminal (replace `<ide>-debugger` with your IDE name):
149 
150```bash
151codex mcp add intellij-debugger -- npx -y mcp-remote http://127.0.0.1:63342/debugger-mcp/sse --allow-http
152```
153 
154To remove: `codex mcp remove intellij-debugger` (use your IDE's name)
155 
156### Cursor
157 
158Add to `.cursor/mcp.json` in your project root or `~/.cursor/mcp.json` globally:
159 
160```json
161{
162  "mcpServers": {
163    "intellij-debugger": {
164      "url": "http://127.0.0.1:63342/debugger-mcp/sse"
165    }
166  }
167}
168```
169 
170### Windsurf
171 
172Add to `~/.codeium/windsurf/mcp_config.json`:
173 
174```json
175{
176  "mcpServers": {
177    "intellij-debugger": {
178      "serverUrl": "http://127.0.0.1:63342/debugger-mcp/sse"
179    }
180  }
181}
182```
183 
184### VS Code (Generic MCP)
185 
186```json
187{
188  "mcp.servers": {
189    "intellij-debugger": {
190      "transport": "sse",
191      "url": "http://127.0.0.1:63342/debugger-mcp/sse"
192    }
193  }
194}
195```
196 
197> **Note**: Replace `intellij-debugger` with your IDE's server name (see list above).
198 
199> **Note**: Replace `63342` with your actual IDE port if different. Check <kbd>Settings</kbd> > <kbd>Debugger</kbd> > <kbd>Built-in Server Port</kbd>.
200 
201## Available Tools
202 
203The plugin provides **22 MCP tools** organized by category:
204 
205### Run Configuration Tools
206 
207| Tool | Description |
208|------|-------------|
209| `list_run_configurations` | List all available run configurations in the project |
210| `execute_run_configuration` | Execute a run configuration in debug or run mode |
211 
212### Debug Session Tools
213 
214| Tool | Description |
215|------|-------------|
216| `list_debug_sessions` | List all active debug sessions with state and metadata |
217| `start_debug_session` | Start a new debug session for a run configuration |
218| `stop_debug_session` | Stop/terminate a debug session |
219| `get_debug_session_status` | Get comprehensive status (variables, stack, source) in one call |
220 
221### Breakpoint Tools
222 
223| Tool | Description |
224|------|-------------|
225| `list_breakpoints` | List all breakpoints with optional filtering |
226| `set_breakpoint` | Set a line breakpoint with condition, log message, suspend policy |
227| `remove_breakpoint` | Remove a breakpoint by ID or location |
228 
229### Execution Control Tools
230 
231| Tool | Description |
232|------|-------------|
233| `resume_execution` | Resume paused execution |
234| `pause_execution` | Pause running execution |
235| `step_over` | Step over to next line (without entering methods) |
236| `step_into` | Step into method calls |
237| `step_out` | Step out of current method |
238| `run_to_line` | Continue execution until a specific line |
239 
240### Stack & Thread Tools
241 
242| Tool | Description |
243|------|-------------|
244| `get_stack_trace` | Get current call stack with file/line/method info |
245| `select_stack_frame` | Change debugger context to a different stack frame |
246| `list_threads` | List all threads with state information |
247 
248### Variable Tools
249 
250| Tool | Description |
251|------|-------------|
252| `get_variables` | Get all variables visible in current stack frame |
253| `set_variable` | Modify a variable's value during debugging |
254 
255### Navigation Tools
256 
257| Tool | Description |
258|------|-------------|
259| `get_source_context` | Get source code around current execution point |
260 
261### Evaluation Tools
262 
263| Tool | Description |
264|------|-------------|
265| `evaluate_expression` | Evaluate an expression or code fragment in debug context |
266 
267> **Note**: For detailed tool documentation with parameters, examples, and response formats, see [USAGE.md](USAGE.md).
268 
269## Multi-Project Support
270 
271When multiple projects are open in a single IDE window, you must specify which project to use with the `project_path` parameter:
272 
273```json
274{
275  "name": "set_breakpoint",
276  "arguments": {
277    "project_path": "/Users/dev/myproject",
278    "file_path": "/Users/dev/myproject/src/Main.java",
279    "line": 42
280  }
281}
282```
283 
284If `project_path` is omitted:
285- **Single project open**: That project is used automatically
286- **Multiple projects open**: An error is returned with the list of available projects
287 
288## Tool Window
289 
290The plugin adds a "Debugger MCP Server" tool window (bottom panel) that shows:
291 
292- **Server Status**: Running indicator with server URL and port
293- **Project Name**: Currently active project
294- **Command History**: Log of all MCP tool calls with:
295  - Timestamp
296  - Tool name
297  - Status (Success/Error/Pending)
298  - Parameters and results (expandable)
299  - Execution duration
300 
301### Tool Window Actions
302 
303| Action | Description |
304|--------|-------------|
305| Refresh | Refresh server status and command history |
306| Copy URL | Copy the MCP server URL to clipboard |
307| Clear History | Clear the command history |
308| Export History | Export history to JSON or CSV file |
309| **Install on Coding Agents** | Install MCP server on AI assistants (prominent button on right) |
310 
311## Error Codes
312 
313### JSON-RPC Standard Errors
314 
315| Code | Name | Description |
316|------|------|-------------|
317| -32700 | Parse Error | Failed to parse JSON-RPC request |
318| -32600 | Invalid Request | Invalid JSON-RPC request format |
319| -32601 | Method Not Found | Unknown method name |
320| -32602 | Invalid Params | Invalid or missing parameters |
321| -32603 | Internal Error | Unexpected internal error |
322 
323### Custom MCP Errors
324 
325| Code | Name | Description |
326|------|------|-------------|
327| -32001 | Session Not Found | Debug session not found |
328| -32002 | File Not Found | Specified file does not exist |
329| -32003 | Not Paused | Operation requires paused session |
330| -32004 | Breakpoint Error | Failed to set/remove breakpoint |
331| -32005 | Evaluation Error | Expression evaluation failed |
332 
333## Settings
334 
335Configure the plugin at <kbd>Settings</kbd> > <kbd>Tools</kbd> > <kbd>Debugger MCP Server</kbd>:
336 
337| Setting | Default | Description |
338|---------|---------|-------------|
339| Server Port | 0 (auto) | Set specific port or 0 for auto-assign |
340| Max History Size | 100 | Maximum number of commands to keep in history |
341| Auto-scroll | true | Auto-scroll to new commands in history |
342| Show Notifications | true | Show notifications for server events |
343 
344## Requirements
345 
346- **JetBrains IDE** 2025.1 or later (any IDE based on IntelliJ Platform)
347- **JVM** 21 or later
348- **MCP Protocol** 2024-11-05
349 
350### Supported IDEs
351 
352**Fully tested**: IntelliJ IDEA, PyCharm, WebStorm, GoLand, RustRover, Android Studio, PhpStorm
353**May work** (untested): RubyMine, CLion, DataGrip
354 
355## Architecture
356 
357The plugin supports **dual MCP transports** on the IDE's built-in web server:
358 
359### SSE Transport (MCP Inspector, spec-compliant clients)
360 
361```
362AI Assistant ──────► GET /debugger-mcp/sse           (establish SSE stream)
363                     ◄── event: endpoint             (receive POST URL with sessionId)
364             ──────► POST /debugger-mcp?sessionId=x  (JSON-RPC requests)
365                     ◄── HTTP 202 Accepted
366                     ◄── event: message              (JSON-RPC response via SSE)
367```
368 
369### Streamable HTTP Transport (Claude Code, simple clients)
370 
371```
372AI Assistant ──────► POST /debugger-mcp              (JSON-RPC requests)
373                     ◄── JSON-RPC response           (immediate HTTP response)
374```
375 
376This dual approach:
377- **MCP Inspector compatible** - Full SSE transport per MCP spec (2024-11-05)
378- **Claude Code compatible** - Streamable HTTP for simple request/response
379- Requires no additional ports or processes
380- Works with any MCP-compatible client
381- Automatically adapts to the IDE's server port
382 
383## Contributing
384 
385Contributions are welcome! Please:
386 
3871. Fork the repository
3882. Create a feature branch
3893. Make your changes
3904. Run tests: `./gradlew test`
3915. Submit a pull request
392 
393### Development Setup
394 
395```bash
396# Build the plugin
397./gradlew build
398 
399# Run IDE with plugin installed
400./gradlew runIde
401 
402# Run tests
403./gradlew test
404 
405# Run plugin verification
406./gradlew runPluginVerifier
407```
408 
409## License
410 
411This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
412 
413---
414 
415Plugin based on the [IntelliJ Platform Plugin Template](https://github.com/JetBrains/intellij-platform-plugin-template).
416