xdebug

Xdebug MCP

Debug PHP with Runtime Data — No var_dump(), No Guesswork

Trace-based debugging for PHP, built on Xdebug. Drive the tools from the CLI, or let an AI assistant run the core tools through plugin, Skill, or MCP integration.

---

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のテストカバレッジを確認して"

When connected through the plugin, Skill, or an MCP-capable client, the AI can select the appropriate tool, execute it, and analyze the results.

Requirements

• PHP 8.2+
• Xdebug 3.x extension (installed, but not enabled by default)
• Optional: an AI assistant (Claude Code plugin, Codex Skill, or any MCP-capable client)

💡 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 global config bin-dir --absolute --quiet)/check-env"

3. (Optional) Wire up an AI assistant

Claude Code — install the plugin:

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

Codex CLI — install the Skill:

git clone --depth 1 https://github.com/koriym/xdebug-mcp.git /tmp/xdebug-mcp
mkdir -p ~/.codex/skills
cp -r /tmp/xdebug-mcp/skills/xdebug ~/.codex/skills/

Any MCP-capable client — see MCP Configuration below.

You can skip this step entirely and use the CLI tools directly.

4. 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 (raw mode for plain PHP scripts)
./bin/xcoverage --raw -- php demo/coverage.php

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

# Compare variable states with different inputs
./bin/xcompare --break="demo/buggy.php:22" --run-a="php demo/buggy.php 10" --run-b="php demo/buggy.php 0"

# Compare current code vs another branch
./bin/xcompare --break="src/calc.php:25" --run="php src/calc.php 10" --compare-with=main

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"
xcompare	Compare variable states across two runs	"Compare input 10 vs 0" or "Compare with main branch"

All tools in this table are available as CLI commands. MCP currently exposes the core one-shot analysis tools: xtrace, xprofile, xstep, xcoverage, and xback. xcompare is CLI-only.

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' -- php script.php

# Pretty-print JSON, truncate long values, limit nesting depth
xstep --break='script.php:42' --pretty --max-value-bytes=200 --max-depth=3 -- php script.php