Compatible platform for the VSCode debugging extension with file-based IPC
Fully tested and supported platform for the VSCode debugging extension with file-based IPC
Enables running debugging sessions with Node.js applications through VSCode's debugging API
Provides debugging capabilities for TypeScript code, allowing for setting breakpoints and controlling debug sessions
MCP Debugger Tools
VSCode extension that exposes debugging capabilities via Model Context Protocol (MCP), enabling AI agents to programmatically control VSCode's debugger.
Features
The extension provides the following 4 MCP tools:
add_breakpoint - Add a breakpoint to a specific file and line number
remove_breakpoint - Remove a breakpoint from a specific file and line number
start_debugging - Start debugging with a specific configuration
stop_debugging - Stop the current debugging session
Installation & Setup
Clone and build the extension:
git clone <repository-url> cd vscode-mcp-debugger npm install npm run compileInstall the extension in VSCode:
Press
F5
to run in Extension Development Host, orPackage as VSIX:
vsce package
and install manually
Verify the MCP server is available:
Open VSCode Command Palette (
Cmd+Shift+P
)Run "MCP: List Servers"
You should see "MCP Debugger Tools" listed
Enable in AI Chat:
Open AI Chat in VSCode
Click the tools icon or type
/
to see available toolsYou should see the 4 debugging tools available
Usage with AI Agents
Once installed, AI agents can use these tools to:
Set breakpoints in your code at specific lines
Start debugging sessions using your launch configurations
Remove breakpoints when no longer needed
Stop debugging to clean up resources
Communication Architecture
The extension uses a unique architecture to bridge the MCP protocol with VSCode's debugging APIs:
How it works:
AI Agent calls MCP tools (add_breakpoint, start_debugging, etc.)
MCP Server (standalone Node.js process) receives the tool calls
File-based IPC - Server writes command requests to temporary files
VSCode Extension monitors temp directory and processes commands
VSCode Debug API - Extension uses native VSCode debugging capabilities
Response cycle - Results flow back through the same IPC mechanism
This architecture ensures the MCP server runs independently while having full access to VSCode's debugging features.
Example AI Agent Workflow
MCP Tools Reference
add_breakpoint
Description: Add a breakpoint to a specific file and line number
Parameters:
filePath
(string, required): Absolute path to the filelineNumber
(number, required): Line number (1-based)condition
(string, optional): Conditional expression for the breakpoint
Example:
remove_breakpoint
Description: Remove a breakpoint from a specific file and line number
Parameters:
filePath
(string, required): Absolute path to the filelineNumber
(number, required): Line number (1-based)
Example:
start_debugging
Description: Start debugging with a specific configuration
Parameters:
configurationName
(string, optional): Name of the debug configuration to useworkspaceFolderPath
(string, optional): Path to the workspace folder
Example:
stop_debugging
Description: Stop the current debugging session
Parameters:
sessionId
(string, optional): Optional session ID to stop a specific session
Example:
Requirements
VSCode with MCP support (latest version recommended)
Node.js (v18+ for running the MCP server)
Project workspace with debug configurations in
.vscode/launch.json
Extension Development Host (for development/testing)
Supported Platforms
✅ macOS - Fully tested and supported
✅ Linux - Compatible with file-based IPC
✅ Windows - Should work with standard temp directory
⚠️ WSL - May require additional configuration for file permissions
Debug Configuration Setup
Create a .vscode/launch.json
file in your project:
Development
Building from Source
Install dependencies:
npm install
Compile TypeScript:
npm run compile
Watch for changes:
npm run watch
for automatic compilationTesting: Use the Extension Development Host (F5)
Debugging: Set breakpoints in the extension code itself
Project Structure
Key Components
Extension.ts: Registers MCP server definition, monitors IPC files
DebugBridge.ts: Provides clean interface to VSCode debugging APIs
mcpServer.ts: Standalone MCP server that communicates via file IPC
IPC System: File-based communication between processes
Contributing
Fork the repository
Create a feature branch
Make your changes
Test with Extension Development Host
Submit a pull request
Please ensure all tools work correctly and add appropriate error handling.
Troubleshooting
Common Issues
Tools not visible:
Check that MCP server is running via "MCP: List Servers"
Verify the extension is active in Extension Development Host
Look for "MCP Debugger Tools" in the MCP servers list
Breakpoints not working:
Ensure file paths are absolute and files exist
Check that the file is currently open or can be opened in VSCode
Verify the line number is valid (1-based indexing)
Debug config errors:
Verify
.vscode/launch.json
exists and is validEnsure the specified configuration name exists
Check that the workspace folder is correctly detected
IPC communication issues:
Check VSCode Developer Console for error messages
Verify temp directory permissions (the extension uses OS temp directory)
Look for MCP server stderr output in "MCP: List Servers" → Show Output
Debug Mode
Enable detailed logging by checking the MCP server output:
Open Command Palette (
Cmd+Shift+P
)Run "MCP: List Servers"
Select "MCP Debugger Tools"
Click "Show Output" to see server logs
Technical Details
MCP Server Process: Runs as standalone Node.js process via stdio transport
Extension Process: Runs within VSCode extension host
IPC Mechanism: Temporary JSON files in OS temp directory
Response Timeout: 10 seconds (configurable in source code)
File Cleanup: Automatic cleanup of temporary IPC files
License
MIT
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
A VSCode extension that enables AI agents to programmatically control VSCode's debugging features through the Model Context Protocol (MCP).
Related MCP Servers
- -securityAlicense-qualityAn implementation of the Model Context Protocol (MCP) that enables interaction with debug adapters, allowing language models to control debuggers, set breakpoints, evaluate expressions, and navigate source code during debugging sessions.Last updated -21AGPL 3.0
- AsecurityAlicenseAqualityA Model Context Protocol (MCP) server that helps AI coding assistants identify critical design issues in code, rather than just focusing on cosmetic problems when asked to improve code.Last updated -1517MIT License
- AsecurityFlicenseAqualityA Model Context Protocol (MCP) server for advanced code analysis and editing with semantic search capabilities, enabling AI assistants to perform complex code operations through a standardized interface.Last updated -151
- AsecurityAlicenseAqualityA comprehensive MCP server providing tools for AI agents to interact with code, including reading symbols, importing modules, replacing text, and sending OS notifications.Last updated -34323MIT License