DebugMCP (MCP Server) - Empowering AI Agents with Operational Debugging Capabilities

Let AI agents debug your code inside VS Code - set breakpoints, step through execution, inspect variables, and evaluate expressions. Works with Codex, GitHub Copilot, GitHub Copilot CLI, Claude Code, Cline, Cursor, Windsurf, Roo Code, and any MCP-compatible assistant. Compatible with any VS Code supported coding language.

🚀 DebugMCP CLI is now available on npm! Debug directly from the terminal without requiring VS Code or any IDE at all by connecting AI coding agents to explicitly configured Debug Adapter Protocol (DAP) adapters. The debug adapter and target process run in the background. Install it with npm install --global debugmcp, then run debugmcp configure --agent copilot-cli. The CLI also installs the debug-live skill automatically. View the package on npm

⭐ If you find DebugMCP useful, please star the repo on GitHub! It helps others discover the project and motivates continued development.

📢 Developers Notice: This extension is maintained by ozzafar@microsoft.com and orbarila@microsoft.com. We welcome feedback and contributions to help improve this extension.

🎬 Watch DebugMCP in action — your AI assistant autonomously sets breakpoints, steps through code, and inspects variables directly in VS Code.

<p align="center"> <img src="assets/DebugMCP.gif" width="800"> </p>

✨ What's New

2.4

• Standalone DebugMCP CLI — install debugmcp from npm and give MCP-compatible agents direct access to explicitly configured DAP adapters without running VS Code. The CLI supports any language with a DAP adapter that communicates over stdio, configures supported agents, and installs the debug-live skill automatically.

2.2

• Cross-agent debug-live skill install — the systematic debugging workflow ships as an Agent Skill and is now installed into the standard skills directories — ~/.agents/skills/ (the cross-agent location honored by skills-compatible harnesses, including VS Code agent mode) and ~/.copilot/skills/ when present — so it's discoverable everywhere instead of being copied next to each agent's config where nothing scans it (fixes #105, where VS Code never loaded the skill). The server also advertises MCP instructions and the start_debugging tool points at the skill for the full workflow.
• Pause running programs — new pause_execution tool interrupts a freely-running program and stops at its current location, even with no breakpoint set (great for busy loops and embedded/bare-metal targets), so you can then inspect state or step from there.
• Robust debugging via the VS Code Testing API — start_debugging with a testName uses the VS Code Testing API to discover and launch the test, producing consistent breakpoint hits inside individual test cases across language test runners (pytest, Jest/Vitest, Java, .NET, Go, etc.).

🚀 Quick Install

Install from VS Code Marketplace or use the direct link: vscode:extension/ozzafar.debugmcpextension

Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Supported AI Assistants
• Supported Languages
• Configuration
• FAQ
• Troubleshooting
• How It Works
• Contributing
• License

Overview

DebugMCP is an MCP server that gives AI coding agents full control over the VS Code debugger. Instead of reading logs or guessing, your AI assistant can autonomously set breakpoints, launch debug sessions, step through code line by line, inspect variable values, and evaluate expressions — just like a human developer would. It runs 100% locally, requires zero configuration, and works out of the box with any MCP-compatible AI assistant.

Features

🔧 Tools

| Tool | Description | Parameters | |------|-------------|------------| | start_debugging | Start a debug session for a source code file | fileFullPath (required)<br>workingDirectory (required)<br>testName (optional)<br>configurationName (optional) | | stop_debugging | Stop the current debug session | None | | step_over | Execute the next line (step over function calls) | None | | step_into | Step into function calls | None | | step_out | Step out of the current function | None | | continue_execution | Continue until next breakpoint | None | | pause_execution | Interrupt a freely-running program and stop at its current location (no breakpoint needed) | None | | restart_debugging | Restart the current debug session | None | | add_breakpoint | Add a breakpoint at a specific line (optionally conditional) | fileFullPath (required)<br>line (required, 1-based)<br>condition (optional) | | add_logpoint | Add a logpoint that logs a message (instead of pausing) when a line is reached | fileFullPath (required)<br>line (required, 1-based)<br>logMessage (required, {expr} interpolated)<br>condition (optional) | | remove_breakpoint | Remove a breakpoint from a specific line | fileFullPath (required)<br>line (required) | | clear_all_breakpoints | Remove all breakpoints at once | None | | list_breakpoints | List all active breakpoints | None | | list_variable_names | List names and types of variables in scope, without reading any values | scope (optional: 'local', 'global', 'all') | | get_variables_values | Get the values of specifically named variables at the current execution point | variableNames (required, e.g. ["user","response"])<br>scope (optional: 'local', 'global', 'all') | | evaluate_expression | Evaluate an expression in debug context; expandable children are listed by name and type without their values | expression (required) |

Note: The MCP server exposes tools for debugger actions, while the procedural workflow guidance (when to debug, how to structure a root-cause investigation, language-specific quirks) lives in the companion Agent Skill. Tool descriptions stay terse and behavioral; the extension installs the debug-live skill into the standard skills directories (~/.agents/skills/, plus ~/.copilot/skills/ when present) so skills-compatible harnesses load the full workflow on demand. The server also advertises MCP instructions pointing agents at it before debugging.

🎯 Debugging Best Practices

DebugMCP follows systematic debugging practices for effective issue resolution:

• Start with Entry Points: Begin debugging at function entry points or main execution paths
• Follow the Execution Flow: Use step-by-step execution to understand code flow
• Root Cause Analysis: Don't stop at symptoms - find the underlying cause

🛡️ Security & Reliability

• Secure Communication: All MCP communications use secure protocols
• Local Operation: The MCP server runs 100% locally with no external communications and requires no credentials
• State Validation: Robust validation of debugging states and operations

Installation

Standalone CLI (preview)

The standalone host talks directly to explicitly configured DAP adapters and does not require VS Code. It never discovers, downloads, installs, or selects an adapter automatically.

Install the published package:

npm install --global debugmcp

For repository development, build and invoke the local bundle:

npm install
npm run package
node dist/debugmcp.js adapter add python --command "python -m debugpy.adapter"
node dist/debugmcp.js adapter validate python
node dist/debugmcp.js configure

Adapter registrations are stored in .debugmcp.json by default. Add --user to adapter add, adapter list, or adapter remove to use the per-user configuration. Project registrations override registrations with the same name in user configuration.

Language shorthands derive the DAP type and file extensions for python, csharp, dotnet, cpp, c, javascript, typescript, node, java, go, rust, ruby, php, swift, and dart. These are configuration conveniences, not a language support boundary. The command remains explicit so the selected environment determines which adapter installation is used. Languages without a shorthand provide --type and --extensions explicitly. Compiled-language registrations can provide the executable in --launch; values support ${workspaceFolder}, ${file}, ${fileDirname}, and ${fileBasenameNoExtension}.

The current CLI supports adapters that speak DAP over stdio. A registration can provide adapter-specific launch properties with --launch followed by a JSON object. If multiple registered adapters claim the same file extension, start_debugging.configurationName must identify the adapter to use. Test discovery remains host-specific; configure the adapter launch properties to run the required test command.

Adapter arguments beginning with -- can follow --args directly. Use a standalone -- after --args when an adapter argument has the same name as a DebugMCP option, for example --args -- --user.

debugmcp configure presents the same agent choices as the VS Code extension's setup popup and writes the standalone stdio command for every selected agent. In automation, repeat --agent <id> to bypass the terminal prompt, for example debugmcp configure --agent copilot-cli --agent codex. Each configuration has one canonical debugmcp entry, so configuring the CLI replaces an existing extension HTTP entry rather than registering both. The command also installs the bundled debug-live skill into the standard personal skills directories. Restart configured agents to discover it.

Use debugmcp status to inspect the GitHub Copilot CLI registration. The DebugMCP command configures only the standalone CLI. To use the interactive VS Code version, configure it through the DebugMCP extension's agent popup; the command line does not select or configure the extension.

Quick Install Options

Option 1: Direct Link (Fastest)

• Click this link: vscode:extension/ozzafar.debugmcpextension
• Or copy and paste in your browser: vscode:extension/ozzafar.debugmcpextension

Option 2: VS Code Marketplace

• Visit: https://marketplace.visualstudio.com/items?itemName=ozzafar.debugmcpextension
• Click "Install"

Option 3: Within VS Code

1. Open VSCode
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "DebugMCP"
4. Click Install
5. The extension automatically activates and registers as an MCP server

Verification

After installation, you should see:

• DebugMCP extension in your installed extensions
• MCP server automatically running on port 3001 (configurable)
• Debug tools available to connected AI assistants

📝 Note: No additional debugging rule instructions are needed -