xdebug — MCP server for Claude Code: PHP debugging
Hooks the Xdebug debugger into your agent: breakpoints, stepping, variable and stack inspection from the chat. Useful when a PHP script fails for no obvious reason.
claude mcp add xdebug -- npx -y xdebug-mcpWhat xdebug does
The server speaks DBGp to Xdebug. From the agent you can set a line or conditional breakpoint, step in, step over, step out, resume or stop a session. Variables are readable and writable, and PHP expressions get evaluated in the current frame.
Over forty tools ship with it. Beyond basic control there are persistent watches, logpoints that use {$var} placeholders, memory and time counters between breakpoints, line coverage, and automatic capture of $_GET, $_POST, $_SESSION and headers. Several sessions can run at once, and step filters keep the walker out of vendor libraries. Docker works too — but set PATH_MAPPINGS, otherwise container paths won't line up with your host tree. Port 9003 is the one to mirror in xdebug.client_port; inside a container the host goes in as host.docker.internal. A Unix socket via XDEBUG_SOCKET_PATH is an alternative to TCP and has less overhead on your own machine.
What it helps with
- catch the line where a variable takes a wrong value
- walk the call stack of a failing request
- stop only on the exception you care about
- measure memory and time between two points
- see which lines actually ran
Example prompts for the agent
- Set a breakpoint in
src/Order.phpat line 84 and start debugging - List every variable in the active xdebug session
- Add a watch on
$totaland break when it changes
How to install xdebug
Platform CLI
claude mcp add xdebug -- npx -y xdebug-mcpPlatform CLI
codex mcp add xdebug -- npx -y xdebug-mcpConfig file
{
"mcpServers": {
"xdebug": {
"command": "npx",
"args": [
"-y",
"xdebug-mcp"
]
}
}
}Config file
{
"servers": {
"xdebug": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"xdebug-mcp"
]
}
}
}Platform CLI
gemini mcp add xdebug npx -y xdebug-mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about xdebug
How do I install xdebug in Claude Code?
Run one command: claude mcp add xdebug -- npx -y xdebug-mcp. Then point your PHP Xdebug config at port 9003.
What does xdebug do?
It links the agent to Xdebug over DBGp and exposes debug tools: breakpoints, stepping, variables, stack traces and expression evaluation.
Which PHP settings are required?
Set xdebug.mode=debug and xdebug.client_port=9003 in php.ini, plus the host where the server listens. On Linux with Docker you also need host.docker.internal and an extra_hosts entry.
