DBGP Client

DBGP Client is a debugger client for PHP. Its dbgp command speaks DBGp, the protocol of PHP Debugger and Xdebug, and can be used in two ways:

• As a debugging tool for AI agents. dbgp mcp is an MCP server that lets an agent such as Claude Code debug PHP the way you would: set breakpoints, run the code, step through it, and look at the stack, variables, output and warnings.
• As a command-line DBGp client. dbgp on its own is an interactive debugger in your terminal, for when you want to debug PHP yourself without an IDE.

Both work with PHP scripts and web requests, on your local machine or in a container or on a server.

Installation

The install script downloads the latest release for your OS and architecture and installs dbgp system-wide.

macOS / Linux (installs to /usr/local/bin, using sudo if needed):

curl -fsSL https://github.com/php-debugger/dbgp-client/releases/latest/download/install.sh | sh

Windows (PowerShell as administrator; installs to %ProgramFiles%\dbgp and adds it to the system PATH):

powershell -c "irm https://github.com/php-debugger/dbgp-client/releases/latest/download/install.ps1 | iex"

Set INSTALL_DIR to install elsewhere, and VERSION (e.g. 0.1.1) to install a release other than the latest. Run the script again to update. Builds are published for Linux and macOS (amd64 and arm64) and Windows (amd64); elsewhere, install with Go:

go install github.com/php-debugger/dbgp-client/cmd/dbgp@latest

dbgp -version shows the installed version.

To be debugged, PHP needs PHP Debugger or Xdebug: php -v shows which one it has.

Debugging with AI agents

Add dbgp mcp to your agent as an MCP server. For example, for Claude Code:

claude mcp add dbgp -- dbgp mcp

Other agents take the same command, dbgp mcp, in their MCP settings. Then ask the agent to debug something, for example:

Find out why the total on the checkout page is wrong: debug the request to /checkout with a breakpoint in CartService::total().

The agent starts the PHP code itself, as a script or a web request, and debugs it with dbgp's tools: breakpoints, running and stepping, the call stack and variables, the source, what the script printed and the PHP warnings it raised, and evaluating PHP code. dbgp only listens for PHP connections while the agent is debugging, so PHP runs at full speed the rest of the time.

You can optionally add some options after dbgp mcp:

• -no-eval leaves out the tools that run PHP code in the debugged script (evaluating expressions and changing variables), so the agent can only look.
• -map LOCAL=REMOTE maps a directory on this machine to where PHP sees it, for PHP in a container or on a server. The agent can also add mappings itself.
• -addr changes the address dbgp listens on for PHP, localhost:9003 by default.

By default each agent session starts its own dbgp. To keep breakpoints and sessions between agent sessions, and share them between agents, run dbgp in the background:

dbgp mcp start     # start it, with any of the options above
dbgp mcp status    # is it running?
dbgp mcp stop      # stop it

While it runs, agents that start dbgp mcp use it instead, with the options it was started with. After updating dbgp, restart it to use the new version.

dbgp mcp -h lists all the options.

Debugging from the command line

Run dbgp, optionally with breakpoints, then run the PHP code, for example in another terminal:

dbgp -break src/Controller/HomeController.php:25
php app.php

Each script or request that connects becomes a session, stopped at its start. At the prompt, run runs to the next breakpoint, next, step and out step through the code, and stack, vars and print $user["name"] show where it stopped. On a terminal it has line editing, tab completion and history.

Type help at the prompt for all the commands, and see dbgp -h for the options, such as -map for PHP in a container or on a server.