smart-xdebug

Smart XDebug MCP Server enables Claude to debug PHP applications by connecting to your XDebug-enabled debugger. The server bridges high-level debugging intents from Claude to DBGp commands, allowing AI-driven breakpoint handling, variable inspection, and time-travel queries within your running PHP app. Once the MCP server is running, you can configure Claude to target the xdebug MCP server and let it orchestrate debugging sessions against your PHP process. The tool supports automatic path mapping, breakpoint management, and runtime variable tracking to give Claude actionable visibility into your code as it executes.

Prerequisites:\n- Node.js 18+ and npm installed on your machine or CI environment.\n- PHP with XDebug 3.x configured for remote debugging.\n- Access to your MCP workflow configuration (Claude MCP or equivalent).\n\nInstallation steps:\n1) Ensure Node.js is installed.\n2) Install the MCP server globally via npm:\n npm install -g smart-xdebug-mcp\n3) Start the MCP server (via npx in MCP config or run the server directly if you cloned the repo):\n npx -y smart-xdebug-mcp\n4) Verify the server is reachable in your MCP settings. Example MCP config entry will typically look like:\n {\n "mcpServers": {\n "xdebug": {\n "command": "npx",\n "args": ["-y", "smart-xdebug-mcp"]\n }\n }\n }\n5) Configure XDebug in your PHP environment (php.ini or equivalent) with remote debugging enabled and set the correct client host/port to match your MCP environment.\n6) Start using Claude in your MCP-enabled workflow to issue debugging requests.

Tips and notes:\n- Environment variables for advanced behavior: XDEBUG_MCP_PORT (default 9003), XDEBUG_MCP_TIMEOUT (default 30000 ms), XDEBUG_MCP_WATCHDOG_TIMEOUT (default 300000 ms). Adjust ports if running inside containers or across networks.\n- Path mappings are auto-detected from .vscode/launch.json or docker-compose.yml where possible. Ensure your PHP project paths align with these mappings for accurate debugging.\n- If you run PHP inside Docker, the XDebug client_host should be set to a reachable host (e.g., host.docker.internal) as documented.\n- When debugging in containerized environments, ensure the container exposes the XDebug port and that the MCP server can reach it.\n- Common issues often relate to mismatched XDebug modes, incorrect client ports, or firewall rules blocking the debugging connection.\n- This MCP server is designed to work with Claude Code or any MCP-compatible AI assistant capable of sending debugging intents and receiving structured responses.\n- Restart the MCP server after changing environment variables or updates to the smart-xdebug-mcp package.