DAP-MCP: Debug Adapter Protocol for AI Agents

An MCP (Model Context Protocol) server that gives AI agents the ability to debug code. Launch debug sessions, set breakpoints, inspect variables, and step through code - all through natural language.

Why DAP-MCP?

Traditional debugging requires manually setting breakpoints, stepping through code, and inspecting state. DAP-MCP exposes these capabilities to LLMs, enabling:

• AI-assisted debugging: "Find why this function returns null"
• Automated testing: Set breakpoints and verify variable states
• Code understanding: Inspect runtime behavior to understand complex logic
• Token-efficient: Compound tools like debug_snapshot reduce API calls

Supported Languages

Language	Debug Adapter	Status
Go	Delve	Full support
Python	debugpy	Full support
JavaScript	vscode-js-debug	Full support
TypeScript	vscode-js-debug	Full support
React/Vue/Svelte	vscode-js-debug + Chrome	Full support
C	LLDB / GDB	Full support
C++	LLDB / GDB	Full support
Rust	LLDB / GDB	Full support
Objective-C	LLDB	Full support
Swift	LLDB	Full support

Quick Start

1. Install DAP-MCP

One-line install (recommended):

curl -sSL https://raw.githubusercontent.com/ctagard/dap-mcp/main/scripts/install.sh | bash

This auto-detects your OS and installs using the best method:

• macOS: Homebrew (if available) or binary
• Debian/Ubuntu: .deb package
• Fedora/RHEL: .rpm package
• Other Linux: Binary

Options via environment variables:

# Install specific version
curl -sSL ... | INSTALL_VERSION=0.1.1 bash

# Install to custom directory
curl -sSL ... | INSTALL_DIR=$HOME/.local/bin bash

# Force binary install (skip package managers)
curl -sSL ... | INSTALL_METHOD=binary bash

Homebrew (macOS/Linux):

brew install ctagard/tap/dap-mcp

Debian/Ubuntu:

curl -LO https://github.com/ctagard/dap-mcp/releases/latest/download/dap-mcp_0.1.1_linux_amd64.deb
sudo dpkg -i dap-mcp_0.1.1_linux_amd64.deb

Fedora/RHEL/CentOS:

curl -LO https://github.com/ctagard/dap-mcp/releases/latest/download/dap-mcp_0.1.1_linux_amd64.rpm
sudo rpm -i dap-mcp_0.1.1_linux_amd64.rpm

Go Install:

go install github.com/ctagard/dap-mcp/cmd/dap-mcp@latest

docker pull ghcr.io/ctagard/dap-mcp:latest

# Run with stdio (for MCP)
docker run -i ghcr.io/ctagard/dap-mcp:latest

Download the appropriate archive from the releases page:

# macOS (Apple Silicon)
curl -L https://github.com/ctagard/dap-mcp/releases/download/v0.1.1/dap-mcp_0.1.1_darwin_arm64.tar.gz | tar xz
sudo mv dap-mcp /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/ctagard/dap-mcp/releases/download/v0.1.1/dap-mcp_0.1.1_darwin_amd64.tar.gz | tar xz
sudo mv dap-mcp /usr/local/bin/

# Linux (amd64)
curl -L https://github.com/ctagard/dap-mcp/releases/download/v0.1.1/dap-mcp_0.1.1_linux_amd64.tar.gz | tar xz
sudo mv dap-mcp /usr/local/bin/

# Linux (arm64)
curl -L https://github.com/ctagard/dap-mcp/releases/download/v0.1.1/dap-mcp_0.1.1_linux_arm64.tar.gz | tar xz
sudo mv dap-mcp /usr/local/bin/

# Windows (amd64)
# Download dap-mcp_0.1.1_windows_amd64.zip from releases page

git clone https://github.com/ctagard/dap-mcp
cd dap-mcp
make build
# Binary is at ./bin/dap-mcp

2. Install Debug Adapters

Install the adapter(s) for languages you want to debug:

# Go - Delve
go install github.com/go-delve/delve/cmd/dlv@latest

# Python - debugpy
pip install debugpy

# JavaScript/TypeScript - vscode-js-debug (see detailed instructions below)

# C/C++/Rust/Objective-C/Swift - LLDB (usually pre-installed on macOS)
# macOS: Included with Xcode Command Line Tools
xcode-select --install

# Linux (Ubuntu/Debian)
sudo apt install lldb

# Linux (Fedora)
sudo dnf install lldb

# Or use GDB instead
sudo apt install gdb   # Debian/Ubuntu
sudo dnf install gdb   # Fedora

3. Configure Your AI Client

Add to ~/.claude.json:

{
  "mcpServers": {
    "dap-mcp": {
      "command": "dap-mcp",
      "args": ["--mode", "full"]
    }
  }
}

Or with a config file:

{
  "mcpServers": {
    "dap-mcp": {
      "command": "dap-mcp",
      "args": ["--config", "/path/to/dap-mcp-config.json"]
    }
  }
}

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "dap-mcp": {
      "command": "/usr/local/bin/dap-mcp",
      "args": ["--mode", "full"]
    }
  }
}

Add to your settings (Cmd/Ctrl + Shift + P → "Preferences: Open User Settings (JSON)"):

{
  "mcp.servers": {
    "dap-mcp": {
      "command": "/usr/local/bin/dap-mcp",
      "args": ["--mode", "full"]
    }
  }
}

Add to ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "/usr/local/bin/dap-mcp",
          "args": ["--mode", "full"]
        }
      }
    ]
  }
}

DAP-MCP uses stdio transport. Configure your client with:

• Command: Path to dap-mcp binary
• Arguments: ["--mode", "full"] or ["--config", "/path/to/config.json"]
• Transport: stdio

4. Start Debugging!

Ask your AI assistant:

"Debug my Python script at /path/to/script.py. Set a breakpoint at line 42 and show me the variables when it stops there."

"Launch a debug session for my Go program and step through the main function."

"Attach to my React app running at localhost:3000 and debug the button click handler."

Configuration

Command Line Options

dap-mcp [OPTIONS]

OPTIONS:
    --config <path>   Path to configuration file (JSON)
    --mode <mode>     Capability mode: 'readonly' or 'full' (default: full)
    --version         Show version and exit
    --help            Show help message

Configuration File

Create a JSON file for advanced settings:

{
  "mode": "full",
  "allowSpawn": true,
  "allowAttach": true,
  "allowModify": true,
  "allowExecute": true,
  "maxSessions": 10,
  "adapters": {
    "go": {
      "path": "dlv",
      "buildFlags": "-gcflags='all=-N -l'"
    },
    "python": {
      "pythonPath": "python3"
    },
    "node": {
      "nodePath": "node",
      "jsDebugPath": "/path/to/vscode-js-debug/src/dapDebugServer.js",
      "sourceMapPathOverrides": {
        "/*": "${webRoot}/*",
        "webpack:///src/*": "${webRoot}/src/*"
      }
    }
  }
}

Security Modes

Mode	Description	Use Case
full	All debugging capabilities	Development, trusted environments
readonly	Inspect only, no execution control	Production monitoring, untrusted code

Fine-grained permissions:

• allowSpawn: Can start new debug processes
• allowAttach: Can attach to running processes
• allowModify: Can modify variable values
• allowExecute: Can evaluate arbitrary expressions

Available Tools

DAP-MCP provides a streamlined 12-tool API designed for LLM efficiency.

Session Management (4 tools)

Tool	Description
debug_launch	Launch a new debug session. Supports direct args OR VS Code launch.json configs
debug_attach	Attach to a running process or browser
debug_disconnect	End a debug session
debug_list_sessions	List all active debug sessions

Inspection (2 tools - available in all modes)

Tool	Description
debug_snapshot	Primary inspection tool - Get complete state (threads, stack, scopes, variables) in ONE call
debug_evaluate	Evaluate single or multiple expressions. Supports batch mode with expressions JSON array

Control (6 tools - full mode only)

Tool	Description
debug_breakpoints	Set breakpoints in a source file (replaces all breakpoints in file)
debug_step	Step with type: 'over' (next line), 'into' (enter function), 'out' (exit function)
debug_continue	Continue execution until next breakpoint
debug_pause	Pause program execution
debug_set_variable	Modify a variable's value
debug_run_to_line	Run to specific line and return snapshot (combines breakpoint + continue + snapshot)

Language-Specific Setup

Go

Delve is the standard Go debugger. Install it:

go install github.com/go-delve/delve/cmd/dlv@latest

Verify installation:

dlv version

Python

debugpy is Microsoft's debug adapter for Python:

pip install debugpy

For virtual environments, ensure debugpy is installed in the environment you're debugging.

JavaScript/TypeScript (Node.js)

vscode-js-debug is required for JavaScript/TypeScript debugging:

Option 1: Download pre-built

# Download from releases
curl -L https://github.com/anthropics/dap-mcp/releases/latest/download/js-debug.tar.gz -O
tar xzf js-debug.tar.gz -C ~/.local/share/

Option 2: Build from source

git clone https://github.com/microsoft/vscode-js-debug
cd vscode-js-debug
npm install --legacy-peer-deps
npx gulp vsDebugServerBundle
mv dist src  # The server expects files in src/

Configure the path in your dap-mcp config:

{
  "adapters": {
    "node": {
      "jsDebugPath": "/path/to/vscode-js-debug/src/dapDebugServer.js"
    }
  }
}

C/C++/Rust (LLDB)

LLDB is the recommended debugger for C, C++, Rust, Objective-C, and Swift:

# macOS - included with Xcode Command Line Tools
xcode-select --install

# Verify installation
lldb --version

For Linux, install LLDB:

# Ubuntu/Debian
sudo apt install lldb

# Fedora
sudo dnf install lldb

Compile your code with debug symbols:

# C/C++
gcc -g -O0 myprogram.c -o myprogram
g++ -g -O0 myprogram.cpp -o myprogram
clang -g -O0 myprogram.c -o myprogram

# Rust
cargo build  # Debug build includes symbols by default

C/C++ (GDB)

GDB is an alternative debugger, especially on Linux:

# Ubuntu/Debian
sudo apt install gdb

# Fedora
sudo dnf install gdb

# Verify installation
gdb --version

React/Vue/Svelte (Browser Debugging)

For frontend frameworks, you debug through Chrome:

1. Start your dev server: npm run dev
2. Use target: "chrome" with the URL:

{
  "tool": "debug_launch",
  "args": {
    "language": "javascript",
    "target": "chrome",
    "program": "http://localhost:3000",
    "webRoot": "/path/to/your/project"
  }
}

For source map resolution with bundlers (Vite, Webpack, etc.), configure sourceMapPathOverrides:

{
  "adapters": {
    "node": {
      "jsDebugPath": "/path/to/dapDebugServer.js",
      "sourceMapPathOverrides": {
        "/*": "${webRoot}/*",
        "webpack:///src/*": "${webRoot}/src/*",
        "webpack:///./*": "${webRoot}/*"
      }
    }
  }
}

Example Workflows

Debug a Go Program

User: Debug main.go and stop at line 42

AI uses:
1. debug_launch(language="go", program="./main.go", stopOnEntry=true)
2. debug_run_to_line(path="main.go", line=42)  → Returns snapshot with stack and variables

Debug a Python Script

User: Why does process_data return None for this input?

AI uses:
1. debug_launch(language="python", program="script.py", stopOnEntry=true)
2. debug_run_to_line(path="script.py", line=45)  → Runs to return statement
3. debug_evaluate(expressions='["result", "len(data)", "type(data)"]')  → Batch evaluate
4. Analyzes variable state to explain the bug

Debug a React App

User: Debug the click handler in App.jsx

AI uses:
1. debug_launch(language="javascript", target="chrome",
                program="http://localhost:3000", webRoot="/path/to/project")
2. debug_breakpoints(path="/path/to/project/src/App.jsx",
                     breakpoints='[{"line": 25}]')
3. [User clicks button in browser]
4. debug_snapshot() → Returns component state, props at breakpoint

Use VS Code launch.json Configuration

User: Debug my project using the "Python: Tests" configuration

AI uses:
1. debug_launch(configName="Python: Tests", workspace="/path/to/project")
   → Loads settings from .vscode/launch.json, resolves ${workspaceFolder}, etc.
2. debug_snapshot() → Returns state at entry point

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     Claude / Cursor / AI Client                  │
│                           (MCP Client)                           │
└─────────────────────┬───────────────────────────────────────────┘
                      │ MCP Protocol (JSON-RPC 2.0 over stdio)
┌─────────────────────▼───────────────────────────────────────────┐
│                       DAP-MCP Server                             │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  MCP Handler → Session Manager → DAP Client             │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────┬───────────────────────────────────────────┘
                      │ DAP Protocol (JSON over TCP)
┌─────────────────────▼───────────────────────────────────────────┐
│  ┌──────────┐  ┌──────────┐  ┌─────────────────────────────┐    │
│  │   Delve  │  │ debugpy  │  │      vscode-js-debug        │    │
│  │   (Go)   │  │ (Python) │  │   (JavaScript/TypeScript)   │    │
│  └──────────┘  └──────────┘  └──────────────┬──────────────┘    │
└──────────────────────────────────────────────│──────────────────┘
                                               │ CDP
                                     ┌─────────▼─────────┐
                                     │  Node.js / Chrome │
                                     └───────────────────┘

Troubleshooting

"dlv not found" / "debugpy not found"

Ensure the debug adapter is in your PATH. For Go:

export PATH="$PATH:$(go env GOPATH)/bin"

"jsDebugPath not configured"

You need to install vscode-js-debug and configure its path. See JavaScript/TypeScript setup.

Breakpoints show "Unbound"

For browser debugging, this usually means source maps aren't resolving correctly. Try:

1. Ensure webRoot points to your project root
2. Configure sourceMapPathOverrides for your bundler
3. Check that source maps are enabled in your bundler config

"Connection refused" on attach

Ensure the target process is:

1. Running with debug flags (--inspect for Node, --remote-debugging-port for Chrome)
2. Listening on the expected port

Session times out

Increase the timeout in your config:

{
  "sessionTimeout": "60m"
}

Development

# Build
make build

# Run tests
make test

# Run linter
make lint

# Build for all platforms
make build-all

Related Projects

• Model Context Protocol - The protocol this server implements
• Debug Adapter Protocol - The debugging protocol used internally
• Delve - Go debugger
• debugpy - Python debug adapter
• vscode-js-debug - JavaScript debug adapter

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.