microsoft/DebugMCP

microsoft/DebugMCP

Description: Gift your VS Code agent a real debugger: breakpoints, stepping, inspection.

Language: TypeScript

License: MIT

Stars: 388

Forks: 36

Open issues: 32

Created: 2025-09-30T14:04:04Z

Pushed: 2026-06-20T02:29:30Z

Default branch: main

Fork: no

Archived: no

README:

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, Cline, Cursor, Windsurf, Roo Code, and any MCP-compatible assistant. Compatible with any VS Code supported coding language.

> ⭐ If you find DebugMCP useful, please [star the repo on GitHub](https://github.com/microsoft/DebugMCP)! It helps others discover the project and motivates continued development.

> 📢 Developers Notice: This extension is maintained by [ozzafar@microsoft.com](mailto:ozzafar@microsoft.com) and [orbarila@microsoft.com](mailto: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.

✨ What's New in 2.0.0

• `/really-debug` Agent Skill — DebugMCP now ships a companion [Agent Skill](./skills/really-debug/SKILL.md) that is auto-installed into each configured harness's personal skills directory (e.g. ~/.copilot/skills/really-debug/). Invoke it with /really-debug in supporting agents to load the systematic debugging workflow and trigger DebugMCP tools with the right context.
• Robust debugging via the VS Code Testing API — start_debugging with a testName now uses the VS Code Testing API to discover and launch the test, replacing the previous best-effort path. This works reliably across language test runners that integrate with the Testing API (pytest, Jest/Vitest, Java, .NET, Go, etc.) and produces consistent breakpoint hits inside individual test cases.

🚀 Quick Install

[Install from VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=ozzafar.debugmcpextension) or use the direct link: vscode:extension/ozzafar.debugmcpextension

Table of Contents

• [Overview](#overview)
• [Features](#features)
• [Installation](#installation)
• [Quick Start](#quick-start)
• [Supported AI Assistants](#supported-ai-assistants)
• [Supported Languages](#supported-languages)
• [Configuration](#configuration)
• [FAQ](#faq)
• [Troubleshooting](#troubleshooting)
• [How It Works](#how-it-works)
• [Contributing](#contributing)
• [License](#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) workingDirectory (required) testName (optional) 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 | | restart_debugging | Restart the current debug session | None | | add_breakpoint | Add a breakpoint at a specific line | fileFullPath (required) lineContent (required) | | remove_breakpoint | Remove a breakpoint from a specific line | fileFullPath (required) line (required) | | clear_all_breakpoints | Remove all breakpoints at once | None | | list_breakpoints | List all active breakpoints | None | | get_variables_values | Get variables and their values at current execution point | scope (optional: 'local', 'global', 'all') | | evaluate_expression | Evaluate an expression in debug context | expression (required) |

> Note: The MCP server intentionally exposes tools only — no procedural > instructions, no documentation resources. Workflow guidance (when to debug, how to > structure a root-cause investigation, language-specific quirks) lives in the companion > [DebugMCP Agent Skill](./skills/really-debug/SKILL.md) so it can be loaded into an > agent's prompt context independently of the MCP capability surface.

🎯 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

Quick Install Options

Option 1: Direct Link (Fastest)

• Click this link: [vscode:extension/ozzafar.debugmcpextension](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...