What can you do with this server?

The MCP Debugger is a multi-language debugging server that enables AI agents to perform step-through debugging through the Debug Adapter Protocol (DAP). It provides structured API calls with JSON responses for debugging Python, JavaScript/Node.js, Rust, and Go, with a mock adapter for testing. Core Capabilities: * Session Management: Create, list, and close independent debugging sessions for different languages and projects * Breakpoint Control: Set breakpoints at specific file paths and line numbers with support for conditional breakpoints and AI-aware intelligent placement * Execution Control: Start debugging scripts with custom arguments and adapter-specific launch configurations, then step over/into/out, continue execution, or pause (pause currently not implemented) * State Inspection: Retrieve stack traces with optional filtering of internal frames, examine variable scopes (Locals, Globals, etc.) for any frame, and access variables using variablesReference numbers or quickly get local variables for the current frame * Expression Evaluation: Evaluate arbitrary expressions in the debug context to read or modify program state (currently defined but not implemented) * Source Context: Retrieve code snippets around specific lines for better debugging visibility * Language Discovery: List all supported debugging languages with their metadata Key Features: * Auto-detection of language executables (debugpy for Python, js-debug for Node.js, CodeLLDB for Rust) with optional manual path specification * Handles both absolute and relative file paths with validation to prevent crashes * Optional filtering of special variables and internal stack frames for cleaner output * Clean adapter architecture supporting dynamic loading and future language support (Ruby, C/C++) * Flexible deployment via npm, npx (zero-runtime dependencies), or Docker with STDIO and SSE transport modes

Which integrations are available for this server?

Enables step-through debugging for JavaScript applications with tools for managing breakpoints, stack traces, and variable scopes. Supports debugging of Node.js applications, providing tools to control execution and inspect program state through the Debug Adapter Protocol. Provides debugging capabilities for Python code, including setting breakpoints, inspecting variables, and stepping through execution using debugpy. Supports debugging Rust programs and Cargo projects, enabling variable inspection and source context tracking via CodeLLDB. Provides debugging support for TypeScript projects, allowing for interactive code execution and inspection within the MCP environment.

How do I use MCP Debugger?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Debugger debug this Python script and show me the variables at line 15" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-debugger

MCP server for multi-language debugging – give your AI agents debugging superpowers 🚀

codecov npm version Docker Pulls License: MIT

🎯 Overview

mcp-debugger is a Model Context Protocol (MCP) server that provides debugging tools as structured API calls. It enables AI agents to perform step-through debugging of multiple programming languages using the Debug Adapter Protocol (DAP).

🆕 Version 0.18.0: Go debugging support! Debug Go programs with Delve.

🆕 Version 0.17.0: Rust debugging support (Alpha)! Debug Rust programs with CodeLLDB, including Cargo projects, async code, and full variable inspection—plus step commands now return the active source context so agents keep their place automatically.

🔥 Version 0.16.0: JavaScript/Node.js debugging support (Alpha)! Full debugging capabilities with bundled js-debug, TypeScript support, and zero-runtime dependencies via improved npx distribution.

🎬 Demo Video: See the debugger in action!
Recording in progress - This will show an AI agent discovering and fixing the variable swap bug in real-time

✨ Key Features

🌐 Multi-language support – Clean adapter pattern for any language
🐍 Python debugging via debugpy – Full DAP protocol support
🟨 JavaScript (Node.js) debugging via js-debug – VSCode's proven debugger (Alpha)
🦀 Rust debugging via CodeLLDB – Debug Rust & Cargo projects (Alpha)
🐹 Go debugging via Delve – Full DAP support for Go programs

WARNING: On Windows, use the GNU toolchain for full variable inspection. Run mcp-debugger check-rust-binary <path-to-exe> to verify your build and see Rust Debugging on Windows for detailed guidance. NOTE: The published npm bundle ships the Linux x64 CodeLLDB runtime to stay under registry size limits. On macOS or Windows, point the CODELLDB_PATH environment variable at an existing CodeLLDB installation (for example from the VSCode extension) or clone the repo and run pnpm --filter @debugmcp/adapter-rust run build:adapter to vendor your platform binaries locally.

Windows Rust Setup Script

If you're on Windows and want the quickest path to a working GNU toolchain + dlltool configuration, run:

pwsh scripts/setup/windows-rust-debug.ps1

The script installs the stable-gnu toolchain (via rustup), exposes dlltool.exe from rustup's self-contained directory, builds the bundled Rust examples, and (optionally) runs the Rust smoke tests. Add -UpdateUserPath if you want the dlltool path persisted to your user PATH/DLLTOOL variables.

The script will also attempt to provision an MSYS2-based MinGW-w64 toolchain (via winget + pacman) so cargo +stable-gnu has a fully functional dlltool/ld/as stack. If MSYS2 is already installed, it simply reuses it; otherwise it guides you through installing it (or warns so you can install manually).

🧪 Mock adapter for testing – Test without external dependencies
🔌 STDIO and SSE transport modes – Works with any MCP client
📦 Zero-runtime dependencies – Self-contained bundles via tsup (~3 MB)
⚡ npx ready – Run directly with npx @debugmcp/mcp-debugger - no installation needed
📊 1019 tests passing – battle-tested end-to-end
🐳 Docker and npm packages – Deploy anywhere
🤖 Built for AI agents – Structured JSON responses for easy parsing
🛡️ Path validation – Prevents crashes from non-existent files
📝 AI-aware line context – Intelligent breakpoint placement with code context

🚀 Quick Start

For MCP Clients (Claude Desktop, etc.)

Add to your MCP settings configuration:

{ "mcpServers": { "mcp-debugger": { "command": "node", "args": ["C:/path/to/mcp-debugger/dist/index.js", "--log-level", "debug", "--log-file", "C:/path/to/logs/debug-mcp-server.log"], "disabled": false, "autoApprove": ["create_debug_session", "set_breakpoint", "get_variables"] } } }

For Claude Code CLI

For Claude Code users, we provide an automated installation script:

# Clone the repository git clone https://github.com/yourusername/mcp-debugger.git cd mcp-debugger # Run the installation script ./scripts/install-claude-mcp.sh # Verify the connection /home/ubuntu/.claude/local/claude mcp list

Important: The stdio argument is required to prevent console output from corrupting the JSON-RPC protocol. See CLAUDE.md for detailed setup and troubleshooting.

Using Docker

docker run -v $(pwd):/workspace debugmcp/mcp-debugger:latest

⚠️ The Docker image intentionally ships only the Python and JavaScript adapters. Rust debugging requires the local, SSE, or packed deployments where the adapter runs next to your toolchain.

Using npm

npm install -g @debugmcp/mcp-debugger mcp-debugger --help

Or use without installation via npx:

npx @debugmcp/mcp-debugger --help

📸 Screenshot: MCP Integration in Action
This screenshot will show real-time MCP protocol communication with tool calls and JSON responses flowing between the AI agent and debugger.

📚 How It Works

mcp-debugger exposes debugging operations as MCP tools that can be called with structured JSON parameters:

// Tool: create_debug_session // Request: { "language": "python", // or "javascript", "rust", "go", or "mock" for testing "name": "My Debug Session" } // Response: { "success": true, "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7", "message": "Created python debug session: My Debug Session" }

📸 Screenshot: Active Debugging Session
This screenshot will show the debugger paused at a breakpoint with the stack trace visible in the left panel, local variables in the right panel, and source code with line highlighting in the center.

🛠️ Available Tools

Tool	Description	Status
`create_debug_session`	Create a new debugging session	✅ Implemented
`list_debug_sessions`	List all active sessions	✅ Implemented
`set_breakpoint`	Set a breakpoint in a file	✅ Implemented
`start_debugging`	Start debugging a script	✅ Implemented
`get_stack_trace`	Get the current stack trace	✅ Implemented
`get_scopes`	Get variable scopes for a frame	✅ Implemented
`get_variables`	Get variables in a scope	✅ Implemented
`step_over`	Step over the current line	✅ Implemented
`step_into`	Step into a function	✅ Implemented
`step_out`	Step out of a function	✅ Implemented
`continue_execution`	Continue running	✅ Implemented
`close_debug_session`	Close a session	✅ Implemented
`pause_execution`	Pause running execution	❌ Not Implemented
`evaluate_expression`	Evaluate expressions	❌ Not Implemented
`get_source_context`	Get source code context	✅ Implemented

📸 Screenshot: Multi-Session Debugging
This screenshot will show the debugger managing multiple concurrent debug sessions, demonstrating how AI agents can debug different scripts simultaneously with isolated session management.

🏗️ Architecture: Dynamic Adapter Loading

Version 0.10.0 introduces a clean adapter pattern that separates language-agnostic core functionality from language-specific implementations:

┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ │ MCP Client │────▶│ SessionManager│────▶│ AdapterRegistry │ └─────────────┘ └──────────────┘ └─────────────────┘ │ │ ▼ ▼ ┌──────────────┐ ┌─────────────────┐ │ ProxyManager │◀─────│ Language Adapter│ └──────────────┘ └─────────────────┘ │ ┌──────────────┴──────────────────────────────────┐ │ │ ┌───────────┼───────────┬───────────┬───────────┐ │ │ │ │ │ │ │ ┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐ │Python ││JavaScript││Rust ││Go ││Mock │ │Adapter ││Adapter ││Adapter ││Adapter ││Adapter │ └──────────┘└──────────┘└──────────┘└──────────┘└──────────┘

Adding Language Support

Want to add debugging support for your favorite language? Check out the Adapter Development Guide!

💡 Example: Debugging Python Code

Here's a complete debugging session example:

# buggy_swap.py def swap_variables(a, b): a = b # Bug: loses original value of 'a' b = a # Bug: 'b' gets the new value of 'a' return a, b

Step 1: Create a Debug Session

// Tool: create_debug_session // Request: { "language": "python", "name": "Swap Bug Investigation" } // Response: { "success": true, "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7", "message": "Created python debug session: Swap Bug Investigation" }

Step 2: Set Breakpoints

// Tool: set_breakpoint // Request: { "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7", "file": "buggy_swap.py", "line": 2 } // Response: { "success": true, "breakpointId": "28e06119-619e-43c0-b029-339cec2615df", "file": "C:\\path\\to\\buggy_swap.py", "line": 2, "verified": false, "message": "Breakpoint set at C:\\path\\to\\buggy_swap.py:2" }

Step 3: Start Debugging

// Tool: start_debugging // Request: { "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7", "scriptPath": "buggy_swap.py" } // Response: { "success": true, "state": "paused", "message": "Debugging started for buggy_swap.py. Current state: paused", "data": { "message": "Debugging started for buggy_swap.py. Current state: paused", "reason": "breakpoint" } }

Step 4: Inspect Variables

First, get the scopes:

// Tool: get_scopes // Request: { "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7", "frameId": 3 } // Response: { "success": true, "scopes": [ { "name": "Locals", "variablesReference": 5, "expensive": false, "presentationHint": "locals", "source": {} }, { "name": "Globals", "variablesReference": 6, "expensive": false, "source": {} } ] }

Then get the local variables:

// Tool: get_variables // Request: { "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7", "scope": 5 } // Response: { "success": true, "variables": [ {"name": "a", "value": "10", "type": "int", "variablesReference": 0, "expandable": false}, {"name": "b", "value": "20", "type": "int", "variablesReference": 0, "expandable": false} ], "count": 2, "variablesReference": 5 }

📸 Screenshot: Variable Inspection Reveals the Bug
This screenshot will show the TUI visualizer after stepping over line 4, where both variables incorrectly show value 20, clearly demonstrating the variable swap bug. The left panel shows the execution state, the center shows the highlighted code, and the right panel displays the incorrect variable values.

📖 Documentation

📘 Tool Reference – Complete API documentation
🚦 Getting Started Guide – First-time setup
🏗️ Architecture Overview – Multi-language design
🔧 Adapter Development – Add new languages
🔌 Dynamic Loading Architecture – Runtime discovery, lazy loading, caching
🧩 Adapter API Reference – Adapter, factory, loader, and registry contracts
🔄 Migration Guide – Upgrading to v0.15.0 (dynamic loading)
🐍 Python Debugging Guide – Python-specific features
🟨 JavaScript Debugging Guide – JavaScript/TypeScript features
🐹 Go Debugging Guide – Go debugging with Delve
Rust Debugging on Windows - Toolchain requirements and troubleshooting
🤖 AI Integration Guide – Leverage AI-friendly features
🔧 Troubleshooting – Common issues & solutions

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Development setup git clone https://github.com/debugmcp/mcp-debugger.git cd mcp-debugger # Install dependencies and vendor debug adapters pnpm install # All debug adapters (JavaScript js-debug, Rust CodeLLDB) are automatically downloaded # Build the project pnpm build # Run tests pnpm test # Check adapter vendoring status pnpm vendor:status # Force re-vendor all adapters (if needed) pnpm vendor:force

Debug Adapter Vendoring

The project automatically vendors debug adapters during pnpm install:

JavaScript: Downloads Microsoft's js-debug from GitHub releases
Rust: Downloads CodeLLDB binaries for the current platform
CI Environment: Set SKIP_ADAPTER_VENDOR=true to skip vendoring

To manually manage adapters:

# Check current vendoring status pnpm vendor:status # Re-vendor all adapters pnpm vendor # Clean and re-vendor (force) pnpm vendor:force # Clean vendor directories only pnpm clean:vendor

Running Container Tests Locally

We use Act to run GitHub Actions workflows locally:

# Build the Docker image first docker build -t mcp-debugger:local . # Run tests with Act (use WSL2 on Windows) act -j build-and-test --matrix os:ubuntu-latest

See tests/README.md for detailed testing instructions.

📊 Project Status

✅ Production Ready: v0.18.0 with Go debugging support via Delve, Rust adapter (Alpha), and polished multi-language distribution
✅ 1569 tests passing end-to-end
✅ Clean architecture with adapter pattern
🟨 JavaScript/Node.js: Alpha support with full debugging loop
✅ Go: Full debugging support via Delve DAP
🚧 Coming Soon: Ruby, C/C++, and more language adapters
📈 Active Development: Regular updates and improvements

See Roadmap.md for planned features.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Built with:

Model Context Protocol by Anthropic
Debug Adapter Protocol by Microsoft
debugpy for Python debugging

Give your AI the power to debug like a developer – in any language! 🎯

Install Server

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Report Issue

Related Servers

Tools

View all tools

MCP Debugger