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

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

brew install ctagard/tap/dap-mcp

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

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 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

# 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

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

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

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

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

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

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

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)

Inspection (2 tools - available in all modes)

Control (6 tools - full mode only)

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.