Xdebug MCP Server

An MCP (Model Context Protocol) server that provides PHP debugging capabilities through Xdebug's DBGp protocol. This allows AI assistants like Claude to directly debug PHP applications.

Features

Core Debugging

• Full Debug Control: Step into, step over, step out, continue, stop
• Breakpoints: Line breakpoints, conditional breakpoints, exception breakpoints, function call breakpoints
• Variable Inspection: View all variables, get specific variables, set variable values
• Expression Evaluation: Evaluate PHP expressions in the current context
• Stack Traces: View the full call stack
• Multiple Sessions: Debug multiple PHP scripts simultaneously
• Docker Support: Works with PHP running in Docker containers

Advanced Features

• Watch Expressions: Persistent watches that auto-evaluate on each break with change detection
• Logpoints: Log messages without stopping execution using {$var} placeholders
• Memory Profiling: Track memory usage and execution time between breakpoints
• Code Coverage: Track which lines were executed during debugging
• Request Context: Capture $_GET, $_POST, $_SESSION, $_COOKIE, headers automatically
• Step Filters: Skip vendor/library code during stepping
• Debug Profiles: Save and restore breakpoint configurations
• Session Export: Export debug sessions as JSON or HTML reports

Installation

From npm (Recommended)

npm install -g xdebug-mcp

From Source

git clone https://github.com/kpanuragh/xdebug-mcp.git
cd xdebug-mcp
npm install
npm run build

MCP Server Configuration

For Claude Code

Add the xdebug-mcp server to your MCP configuration (.mcp.json or Claude settings):

Using npm global install:

{
  "mcpServers": {
    "xdebug": {
      "command": "xdebug-mcp",
      "env": {
        "XDEBUG_PORT": "9003",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Using npx:

{
  "mcpServers": {
    "xdebug": {
      "command": "npx",
      "args": ["-y", "xdebug-mcp"],
      "env": {
        "XDEBUG_PORT": "9003",
        "LOG_LEVEL": "info"
      }
    }
  }
}

With Path Mappings (for Docker)

When debugging PHP in Docker containers, you need path mappings to translate container paths to host paths:

{
  "mcpServers": {
    "xdebug": {
      "command": "xdebug-mcp",
      "env": {
        "XDEBUG_PORT": "9003",
        "PATH_MAPPINGS": "{\"/var/www/html\": \"/home/user/projects/myapp\"}",
        "LOG_LEVEL": "info"
      }
    }
  }
}

With DBGp Proxy Registration

If you already use a DBGp proxy, keep mcp-config.example.json as the default direct-listener example and start from mcp-config.proxy.example.json for proxy registration.

Proxy mode requires:

• TCP listener mode for xdebug-mcp (not XDEBUG_SOCKET_PATH)
• a unique callback port such as 9006, 9007, or 9008 for XDEBUG_PORT
• DBGP_PROXY_HOST, DBGP_PROXY_PORT, and DBGP_IDEKEY

See the DBGp Proxy Registration Guide for the full setup, multi-agent examples, and PHP/Xdebug proxy configuration.

PHP/Xdebug Configuration

php.ini (or xdebug.ini)

[xdebug]
zend_extension=xdebug

; Enable step debugging
xdebug.mode=debug

; Start debugging on every request
xdebug.start_with_request=yes

; Host where MCP server is running
; For Docker: use host.docker.internal
; For local PHP: use 127.0.0.1
xdebug.client_host=host.docker.internal

; Port where MCP server listens
xdebug.client_port=9003

; IDE key (optional, for filtering)
xdebug.idekey=mcp

Docker Compose

version: '3.8'

services:
  php:
    image: php:8.2-apache
    volumes:
      - ./src:/var/www/html
      - ./xdebug.ini:/usr/local/etc/php/conf.d/99-xdebug.ini
    extra_hosts:
      - "host.docker.internal:host-gateway"  # Required for Linux
    environment:
      - XDEBUG_MODE=debug
      - XDEBUG_CONFIG=client_host=host.docker.internal client_port=9003

Using Unix Domain Sockets

For improved performance and simplified setup on local systems, you can use Unix domain sockets instead of TCP. Unix sockets eliminate network stack overhead and are ideal for debugging on the same machine.

Benefits:

• ⚡ Lower latency (no TCP/IP stack overhead)
• 🔒 Better security (file permissions instead of port binding)
• 📦 Simpler setup (no port management)
• 🚀 Faster communication for local debugging

MCP Configuration (Unix Socket):

{
  "mcpServers": {
    "xdebug": {
      "command": "xdebug-mcp",
      "env": {
        "XDEBUG_SOCKET_PATH": "/tmp/xdebug.sock",
        "LOG_LEVEL": "info"
      }
    }
  }
}

PHP/Xdebug Configuration:

[xdebug]
zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=unix:///tmp/xdebug.sock

Socket File Permissions:

The socket file is created with default permissions. To restrict access, you can:

# After MCP server starts
chmod 600 /tmp/xdebug.sock

# Or use a secure directory
mkdir -p ~/.xdebug && chmod 700 ~/.xdebug
# Then set XDEBUG_SOCKET_PATH=$HOME/.xdebug/xdebug.sock

Automatic Cleanup:

When XDEBUG_SOCKET_PATH is set, the server will:

• Listen on the specified Unix socket instead of TCP port
• Automatically clean up stale socket files on startup (prevents "address in use" errors)
• Automatically clean up socket files on shutdown
• Use the same debugging tools and features as TCP mode

When to Use Unix Sockets:

• ✅ Local PHP development (best performance)
• ✅ Same-machine debugging
• ✅ High-frequency breakpoint hits
• ❌ Remote debugging (use TCP instead)

Unix socket support requested in Issue #1 by @dkd-kaehm

Available MCP Tools (41 Total)

Session Management

Breakpoints

Pending Breakpoints: You can set breakpoints before a debug session starts. These are stored as "pending breakpoints" and automatically applied when a PHP script connects with Xdebug. This is useful for setting up breakpoints before triggering a page load or script execution.

Execution Control

Inspection

Watch Expressions

Logpoints

Profiling

Code Coverage

Debug Profiles

Additional Tools

Usage Examples

Setting a Breakpoint

Use set_breakpoint with file="/var/www/html/index.php" and line=25

Conditional Breakpoint

Use set_breakpoint with file="/var/www/html/api.php", line=42, condition="$userId > 100"

Watch Expression

Use add_watch with expression="$user->email"
Use add_watch with expression="count($items)"

Logpoint