Debugger MCP

Debugger MCP

A VS Code extension that exposes an MCP (Model Context Protocol) server, allowing AI agents like Claude Code and Claude Desktop to control VS Code's debugger. Language-agnostic — works with any debug adapter (Node.js, Python, C++, Go, Rust, Java, etc.).

Features

• 22 MCP tools for full debugger control
• Works with any debugger that implements the Debug Adapter Protocol
• Zero-config for Claude Code — auto-updates ~/.claude.json on activation
• Execution commands block until the debugger stops and return the stop location + local variables in a single response
• Captures program output (stdout/stderr) for inspection

Architecture

Claude Code / Desktop / any MCP client
       |  (HTTP: Streamable HTTP transport)
       v
VS Code Extension (MCP server on localhost:<port>/mcp)
       |  (vscode.debug.* API)
       v
Debug Adapter Protocol → Any Debugger

The extension hosts the MCP server directly inside the VS Code process — no separate server or sidecar needed. On activation it starts a localhost HTTP server (default port 45557) and automatically writes the connection URL to ~/.claude.json.

Installation

VS Code Marketplace

Install from the VS Code Marketplace, or search for "Debugger MCP" in the Extensions view (Ctrl+Shift+X / Cmd+Shift+X).

Or from the command line:

code --install-extension speakeasy.debugger-mcp

The extension activates automatically on startup — no manual setup required. It starts the MCP server and auto-configures Claude Code.

From source (development)

git clone git@github.com:speakeasy-api/debugger-mcp.git
cd debugger-mcp
npm install
npm run compile

Then press F5 in VS Code to launch the Extension Development Host.

MCP Client Configuration

Claude Code (zero-config)

The extension automatically registers itself in ~/.claude.json on activation. No manual setup needed — just install the extension, reload VS Code, and start using Claude Code.

To verify it's configured, run:

claude mcp list

You should see vscode-debugger listed as an HTTP server.

If you prefer to configure manually, or if auto-config is disabled:

claude mcp add --transport http vscode-debugger http://localhost:45557/mcp

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "vscode-debugger": {
      "type": "http",
      "url": "http://localhost:45557/mcp"
    }
  }
}

VS Code (Copilot / other MCP clients)

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "vscode-debugger": {
      "type": "http",
      "url": "http://localhost:45557/mcp"
    }
  }
}

Alternative: stdio transport

A standalone MCP server process is also available for clients that only support stdio transport. See the extension's dist/mcp-server.js — it discovers the running extension via a port file and proxies MCP requests over HTTP.

Settings

| Setting | Default | Description | |---------|---------|-------------| | debuggerMcp.port | 45557 | Preferred port for the MCP server. Falls back to a random port if taken. | | debuggerMcp.autoConfigureClaude | true | Automatically update ~/.claude.json with the MCP server URL on activation. |

Tools

Session Management

| Tool | Description | |------|-------------| | debug_start | Start a debug session from a launch.json config name or inline configuration | | debug_stop | Stop a debug session | | debug_restart | Restart a debug session | | debug_list_sessions | List active debug sessions | | debug_list_configurations | List available launch.json configurations |

Execution Control

| Tool | Description | |------|-------------| | debug_continue | Resume execution until next breakpoint or exit. Returns stop location + locals | | debug_pause | Pause a running program. Returns stop location + locals | | debug_step_over | Step over (next line). Supports count for batch stepping | | debug_step_into | Step into function calls. Supports count for batch stepping | | debug_step_out | Step out of current function. Supports count for batch stepping |

Breakpoints

| Tool | Description | |------|-------------| | debug_set_breakpoint | Set a source breakpoint (supports condition, hit count, logpoint) | | debug_set_function_breakpoint | Set a function-name breakpoint | | debug_remove_breakpoint | Remove by ID, file+line, all in file, or all | | debug_list_breakpoints | List all breakpoints with details | | debug_toggle_breakpoint | Enable/disable a breakpoint without removing it |

State Inspection

| Tool | Description | |------|-------------| | debug_get_threads | List threads | | debug_get_stack_trace | Get call stack for a thread | | debug_get_scopes | Get variable scopes for a stack frame | | debug_get_variables | Get variables in a scope or expand a structured variable | | debug_evaluate | Evaluate an expression in the debug context |

Status & Output

| Tool | Description | |------|-------------| | debug_status | Quick "where am I?" — session, stop location, and locals | | debug_get_output | Get captured program output (stdout/stderr) |

Build Scripts

| Script | Description | |--------|-------------| | npm run compile | Type-check and build both bundles | | npm run build | Production build (minified, no source maps) | | npm run watch | Watch mode for development | | npm run package | Production build + package into .vsix | | npm run check-types | Type-check only (no emit) |

How It Works

1. Extension activates on VS Code startup and starts an HTTP server on localhost:45557
2. MCP endpoint at /mcp uses the Streamable HTTP transport protocol — each client gets its own session
3. Auto-config writes the server URL to ~/.claude.json so Claude Code discovers it automatically
4. Debug commands are forwarded to the VS Code debug API via an in-process DirectClient
5. DAP message interception captures stopped events, program output, and exit codes in real-time
6. Execution commands (continue, step) block until the debugger pauses, then automatically gather the stop location and local variables

Security

• HTTP server binds to 127.0.0.1 only (no network exposure)
• MCP endpoint uses the standard Streamable HTTP transport protocol
• Port file (for legacy stdio transport) includes random auth token and PID for stale-file detection

License

MIT