xdebug-mcp by koriym - MCP Server

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

The tools automatically detect container runtime and configure Xdebug networking.

See for details.

For Developers

See for tool discoverability testing.

AI Native Design

This tool is designed specifically for AI consumption, not adapted from human interfaces.

Debugger for Humans	AI Native (this tool)
Step-by-step interaction	One-shot batch execution
Session management required	Stateless CLI
Multiple tool calls	Single command, complete data
Manual log placement	Automatic full trace

Why it matters:

Fewer tokens: One command returns all data vs. many back-and-forth calls
No session errors: Stateless design eliminates timeout/connection issues
Comprehensive data: xtrace captures everything; AI filters what it needs

Why "xdebug-mcp"?

This project started as an MCP (Model Context Protocol) server for AI-powered PHP debugging. While MCP remains supported for tools like Cursor and Windsurf, we now recommend the plugin approach for Claude Code users — it's simpler and requires no MCP configuration.

The CLI tools (xstep, xtrace, xprofile, xcoverage, xback) work independently of both MCP and plugins.

Resources

Troubleshooting - Setup issues
Forward Trace Guide - AI debugging methodology
llms.txt - LLM-readable documentation
- Why we built this
Xdebug Docs - Official documentation

Stop debugging blind. Just ask your AI.