xdebug-mcp

Xdebug MCP

Debug PHP with Natural Language — No var_dump(), No Guesswork

AI-powered PHP debugging tools using Xdebug's runtime analysis. Works with Claude Code (plugin), Cursor, Windsurf (MCP), and CLI.

---

Natural Language Debugging

Just tell your AI assistant what you want:

English:

"Debug script.php and find why $user is null at line 42"
"Profile api.php and find the performance bottleneck"
"Trace the authentication flow in login.php"
"Check test coverage for UserService"

日本語:

"script.phpをデバッグして、42行目で$userがnullになる原因を調べて"
"api.phpのパフォーマンスボトルネックを見つけて"
"login.phpの認証フローをトレースして"
"UserServiceのテストカバレッジを確認して"

The AI automatically selects the appropriate tool, executes it, and analyzes the results.

Requirements

• PHP 8.1+
• Xdebug 3.x extension (installed, but not enabled by default)
• AI assistant: Claude Code (plugin), Cursor/Windsurf (MCP), or CLI

💡 Performance Tip: Keep Xdebug disabled in php.ini for daily use. This tool loads Xdebug on-demand only when needed.

Quick Start

1. Install

composer global require koriym/xdebug-mcp

2. Verify Xdebug

~/.composer/vendor/bin/check-env

3. Setup AI Integration

Claude Code:

/plugin marketplace add koriym/xdebug-mcp
/plugin install xdebug@xdebug-mcp

Cursor / Windsurf: See MCP Configuration below.

4. Restart your AI assistant and try it

# Download demo files
git clone --depth 1 https://github.com/koriym/xdebug-mcp.git /tmp/xdebug-demo

# Ask Claude to debug
"Debug /tmp/xdebug-demo/demo/buggy.php and find the bugs"

Or use the skill directly:

/xdebug

Try CLI Tools

Run the demo examples to see each tool in action:

# Debug buggy code with breakpoints (JSON output)
./bin/xstep --break="demo/buggy.php:22" -- php demo/buggy.php

# Trace execution flow
./bin/xtrace --context="Debug demo" -- php demo/buggy.php

# Profile performance bottlenecks
./bin/xprofile --json -- php demo/slow.php

# Analyze code coverage
./bin/xcoverage -- php demo/coverage.php

# Get stack trace at breakpoint
./bin/xback --break="demo/buggy.php:44" -- php demo/buggy.php

Each command outputs structured JSON data that AI can analyze to provide debugging insights.

How It Works

flowchart LR
    A[You] -->|"Debug login.php"| B[AI Assistant]
    B -->|CLI / MCP| C[xtrace, xstep, ...]
    C -->|Runtime Analysis| D[Xdebug]
    D -->|JSON| C
    C -->|Results| B
    B -->|Explanation| A

No var_dump(). No code modification. No guesswork.

Available Tools

Tool	Purpose	Example Prompt
xstep	Breakpoint debugging, variable inspection	"Stop at line 42 and show me the variables"
xtrace	Execution flow analysis	"Trace how the request flows through the app"
xprofile	Performance profiling	"Find what's making this endpoint slow"
xcoverage	Code coverage analysis	"Which lines aren't covered by tests?"
xback	Call stack at breakpoint	"Show me how we got to this error"

CLI Usage

For direct command-line usage without AI:

# Trace execution
xtrace -- php script.php

# Profile performance
xprofile -- php api.php

# Debug with conditional breakpoint
xstep --break='script.php:42:$user==null' --exit-on-break -- php script.php

# Code coverage
xcoverage -- vendor/bin/phpunit

# Stack trace at breakpoint
xback --break='app.php:50' -- php app.php

Run --help on any tool for detailed options.

MCP Configuration

For Cursor, Windsurf, and other MCP-compatible tools.

Create .mcp.json in your project root:

{
  "mcpServers": {
    "xdebug": {
      "command": "php",
      "args": ["/Users/YOUR_USERNAME/.composer/vendor/bin/xdebug-mcp"]
    }
  }
}

Find the correct path: which xdebug-mcp

Interactive REPL

For hands-on debugging without AI, use the interactive debugger:

xstep --break="script.php:42" -- php script.php

Commands:

Command	Description
s	Step into function
o	Step over line
out	Step out of function
c	Continue execution
p <var>	Print variable (e.g., p $user)
bt	Show backtrace
l	List source code
q	Quit debugger

Docker Support

All tools work with Docker, Podman, and Kubectl:

xstep --break="/app/script.php:42" --exit-on-break -- \
  docker compose run --rm php php /app/script.php

xtrace -- docker compose run --rm php php /app/script.php