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. |
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
- Extension activates on VS Code startup and starts an HTTP server on
localhost:45557
- MCP endpoint at
/mcp uses the Streamable HTTP transport protocol — each client gets its own session
- Auto-config writes the server URL to
~/.claude.json so Claude Code discovers it automatically
- Debug commands are forwarded to the VS Code debug API via an in-process
DirectClient
- DAP message interception captures stopped events, program output, and exit codes in real-time
- 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
