Xdebug MCP调试工具

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.

1. Install

composer global require koriym/xdebug-mcp

Docker Support

All tools work with Docker, Podman, and Kubectl:

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

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

The tools automatically detect container runtime and configure Xdebug networking.

See tests/docker/README.md for details.

Quick Start

CLI Usage

For direct command-line usage without AI:

```bash

Download demo files

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

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.

MCP Configuration

For any MCP-capable client, register xdebug-mcp in that client's MCP config (e.g. .mcp.json). MCP exposes xtrace, xprofile, xstep, xcoverage, and xback:

{
  "mcpServers": {
    "xdebug": {
      "command": "php",
      "args": ["/ABSOLUTE/PATH/TO/xdebug-mcp"]
    }
  }
}

Find the path with which xdebug-mcp. Restart your client after editing the config.

Try CLI Tools

Run the demo examples to see each tool in action:

```bash

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.

Compare variables at breakpoint with different inputs

xcompare --break='calc.php:25' --run-a='php calc.php 10' --run-b='php calc.php 0'

Compare current code vs main branch

xcompare --break='calc.php:25' --run='php calc.php 10' --compare-with=main ```

Run --help on any tool for detailed options.

Note on xcompare commands: the --run-a, --run-b, and --run values are executed through the shell so that quoting, redirection, and environment variables behave as users expect. Only pass trusted input to these options. Note on --steps: xcompare defaults to --steps=1, since the comparison only needs the variable snapshot at the breakpoint. Pass --steps=N explicitly (e.g. --steps=100) if you want to see how execution diverges between the two runs after the break.