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