PHPackages                             koriym/xdebug-mcp - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Debugging & Profiling](/categories/debugging)
4. /
5. koriym/xdebug-mcp

ActiveLibrary[Debugging & Profiling](/categories/debugging)

koriym/xdebug-mcp
=================

Universal PHP Xdebug MCP Server with AI-optimized debugging support

v0.11.0(6d ago)5227.1k↑14.1%91MITPHPPHP ^8.2CI passing

Since Aug 26Pushed 6d ago1 watchersCompare

[ Source](https://github.com/koriym/xdebug-mcp)[ Packagist](https://packagist.org/packages/koriym/xdebug-mcp)[ Docs](https://koriym.github.io/xdebug-mcp/)[ RSS](/packages/koriym-xdebug-mcp/feed)WikiDiscussions 1.x Synced yesterday

READMEChangelog (10)Dependencies (27)Versions (36)Used By (1)

Xdebug MCP
==========

[](#xdebug-mcp)

[![xdebug-mcp](docs/images/logo.jpeg)](docs/images/logo.jpeg)

**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.

[![AI Native](https://camo.githubusercontent.com/0babaead355c01be31b9a4e0e1f636f32b1fb526311d948d1aec6f220d1a3d9b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f41495f4e61746976652d5945532d677265656e)](https://github.com/koriym/xdebug-mcp)[![Runtime Data](https://camo.githubusercontent.com/1ef947239dd6ef53391b529bf9aaac41a2dc3d9a8b271ec05bf4175695df6022/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f52756e74696d655f446174612d5945532d677265656e)](https://github.com/koriym/xdebug-mcp)[![var_dump](https://camo.githubusercontent.com/2788e93b5e88ba99bb0c7a9aaa7356587990c3a19e9308b3d1c4cb7af3b409fe/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7661725f5f64756d7028292d4e4f2d726564)](https://github.com/koriym/xdebug-mcp)

---

Natural Language Debugging
--------------------------

[](#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
------------

[](#requirements)

- PHP 8.2+
- [Xdebug 3.x](https://xdebug.org/docs/install) 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
-----------

[](#quick-start)

### 1. Install

[](#1-install)

```
composer global require koriym/xdebug-mcp
```

### 2. Verify Xdebug

[](#2-verify-xdebug)

```
"$(composer global config bin-dir --absolute --quiet)/check-env"
```

### 3. (Optional) Wire up an AI assistant

[](#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](#mcp-configuration) below.

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

### 4. Try it

[](#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
-------------

[](#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
------------

[](#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
```

      Loading **No var\_dump(). No code modification. No guesswork.**

Available Tools
---------------

[](#available-tools)

ToolPurposeExample 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
---------

[](#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

# Code coverage
xcoverage -- vendor/bin/phpunit

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

# 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.

Schema-Backed JSON Output
-------------------------

[](#schema-backed-json-output)

Every tool emits JSON with a `$schema` URL, so the output is machine-verifiable and self-describing — no log-string parsing needed:

```
{
  "$schema": "https://koriym.github.io/xdebug-mcp/schemas/xstep.json",
  "breaks": [
    {
      "location": {"file": "demo/buggy.php", "line": 22},
      "variables": {"$user": "NULL", "$id": "42"}
    }
  ],
  "trace": { "...": "..." }
}
```

Schemas live under [docs/schemas/](docs/schemas/). AI assistants — and humans — can verify exactly what each tool captured.

MCP Configuration
-----------------

[](#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.

Interactive REPL
----------------

[](#interactive-repl)

For hands-on debugging without AI, use the interactive debugger (`xrepl`):

```
xrepl --break="script.php:42" -- php script.php
```

**Commands:**

CommandDescription`s`Step into function`o`Step over line`out`Step out of function`c`Continue execution`p `Print variable (e.g., `p $user`)`bt`Show backtrace`l`List source code`q`Quit debuggerDocker Support
--------------

[](#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](tests/docker/README.md) for details.

Debugging Legacy PHP (7.x / 5.x)
--------------------------------

[](#debugging-legacy-php-7x--5x)

While xdebug-mcp itself requires PHP 8.2+, it can debug older PHP versions as long as a compatible Xdebug 3.x release is installed on the target PHP. Simply specify the target PHP binary after `--`:

```
# Debug PHP 7.2 code
xtrace -- /opt/homebrew/opt/php@7.2/bin/php legacy_app.php
xprofile -- /opt/homebrew/opt/php@7.2/bin/php legacy_app.php
xstep --break="legacy_app.php:30" -- /opt/homebrew/opt/php@7.2/bin/php legacy_app.php
```

The tool runs on your modern PHP while the target script executes on the specified PHP binary — provided the specified PHP has a compatible Xdebug 3.x installed. No Docker required. Check the compatibility table below before trying older PHP binaries.

### Xdebug 3.x Compatibility

[](#xdebug-3x-compatibility)

XdebugSupported PHP3.0-3.1PHP 5.4 - 8.03.2PHP 5.6 - 8.33.3PHP 7.0 - 8.43.4PHP 7.4 - 8.5See [Xdebug compatibility](https://xdebug.org/docs/compat) for details.

For Developers
--------------

[](#for-developers)

See [tests/ai/README.md](tests/ai/README.md) for tool discoverability testing.

AI Native Design
----------------

[](#ai-native-design)

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

Debugger for HumansAI Native (this tool)Step-by-step interactionOne-shot batch executionSession management requiredStateless CLIMultiple tool callsSingle command, complete dataManual log placementAutomatic 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

See Also
--------

[](#see-also)

Looking for a different approach? [kpanuragh/xdebug-mcp](https://github.com/kpanuragh/xdebug-mcp) offers 41 MCP tools with session-based interactive debugging — ideal if you prefer step-by-step control.

Why "xdebug-mcp"?
-----------------

[](#why-xdebug-mcp)

This project started as an MCP (Model Context Protocol) server for AI-powered PHP debugging. MCP is still supported for any MCP-capable client, but the CLI is now the primary interface. The core MCP tools (`xstep`, `xtrace`, `xprofile`, `xcoverage`, `xback`) also work as standalone CLI commands; `xcompare` and `xrepl` are CLI-only tools.

Resources
---------

[](#resources)

- [Troubleshooting](https://koriym.github.io/xdebug-mcp/TROUBLESHOOTING) - Setup issues
- [Forward Trace Guide](https://koriym.github.io/xdebug-mcp/debug-guidelines/) - AI debugging methodology
- [llms.txt](https://koriym.github.io/xdebug-mcp/llms.txt) - LLM-readable documentation
- [Motivation](MOTIVATION.md) - Why we built this
- [Xdebug Docs](https://xdebug.org/docs/) - Official documentation

---

**Stop debugging blind. Just ask your AI.**

###  Health Score

55

—

FairBetter than 97% of packages

Maintenance98

Actively maintained with recent releases

Popularity43

Moderate usage in the ecosystem

Community20

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 92.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~16 days

Total

19

Last Release

6d ago

Major Versions

v0.10.2 → 1.x-dev2026-06-26

PHP version history (2 changes)0.1.0PHP ^8.1

v0.9.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/db4fc75ffc631168d0d7143b6f2c24b1534dfb921212bd851c026c5cbbb1344d?d=identicon)[koriym](/maintainers/koriym)

---

Top Contributors

[![koriym](https://avatars.githubusercontent.com/u/529021?v=4)](https://github.com/koriym "koriym (1082 commits)")[![MarjovanLier](https://avatars.githubusercontent.com/u/2212059?v=4)](https://github.com/MarjovanLier "MarjovanLier (42 commits)")[![claude](https://avatars.githubusercontent.com/u/81847?v=4)](https://github.com/claude "claude (38 commits)")[![o0h](https://avatars.githubusercontent.com/u/907122?v=4)](https://github.com/o0h "o0h (4 commits)")[![crishoj](https://avatars.githubusercontent.com/u/20393?v=4)](https://github.com/crishoj "crishoj (3 commits)")[![ruudk](https://avatars.githubusercontent.com/u/104180?v=4)](https://github.com/ruudk "ruudk (2 commits)")[![gmorel](https://avatars.githubusercontent.com/u/2279794?v=4)](https://github.com/gmorel "gmorel (1 commits)")

---

Tags

phpmcpaidebuggingprofilingXdebugtrace

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Type Coverage Yes

### Embed Badge

![Health badge](/badges/koriym-xdebug-mcp/health.svg)

```
[![Health](https://phpackages.com/badges/koriym-xdebug-mcp/health.svg)](https://phpackages.com/packages/koriym-xdebug-mcp)
```

###  Alternatives

[danog/madelineproto

Async PHP client API for the telegram MTProto protocol.

3.5k902.0k23](/packages/danog-madelineproto)[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.7k38.9k](/packages/matomo-matomo)[shopware/platform

The Shopware e-commerce core

3.4k1.5M3](/packages/shopware-platform)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

751291.4k43](/packages/civicrm-civicrm-core)[typo3/cms

TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL.

1.2k1.9M122](/packages/typo3-cms)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.6M574](/packages/shopware-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)