{
  "markdown": "# Xdebug MCP Server\n\n[![npm version](https://badge.fury.io/js/xdebug-mcp.svg)](https://www.npmjs.com/package/xdebug-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nAn MCP (Model Context Protocol) server that provides PHP debugging capabilities through Xdebug's DBGp protocol. This allows AI assistants like Claude to directly debug PHP applications.\n\n## Features\n\n### Core Debugging\n- **Full Debug Control**: Step into, step over, step out, continue, stop\n- **Breakpoints**: Line breakpoints, conditional breakpoints, exception breakpoints, function call breakpoints\n- **Variable Inspection**: View all variables, get specific variables, set variable values\n- **Expression Evaluation**: Evaluate PHP expressions in the current context\n- **Stack Traces**: View the full call stack\n- **Multiple Sessions**: Debug multiple PHP scripts simultaneously\n- **Docker Support**: Works with PHP running in Docker containers\n\n### Advanced Features\n- **Watch Expressions**: Persistent watches that auto-evaluate on each break with change detection\n- **Logpoints**: Log messages without stopping execution using `{$var}` placeholders\n- **Memory Profiling**: Track memory usage and execution time between breakpoints\n- **Code Coverage**: Track which lines were executed during debugging\n- **Request Context**: Capture `$_GET`, `$_POST`, `$_SESSION`, `$_COOKIE`, headers automatically\n- **Step Filters**: Skip vendor/library code during stepping\n- **Debug Profiles**: Save and restore breakpoint configurations\n- **Session Export**: Export debug sessions as JSON or HTML reports\n\n## Installation\n\n### From npm (Recommended)\n\n```bash\nnpm install -g xdebug-mcp\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/kpanuragh/xdebug-mcp.git\ncd xdebug-mcp\nnpm install\nnpm run build\n```\n\n## MCP Server Configuration\n\n### For Claude Code\n\nAdd the xdebug-mcp server to your MCP configuration (`.mcp.json` or Claude settings):\n\n**Using npm global install:**\n\n```json\n{\n  \"mcpServers\": {\n    \"xdebug\": {\n      \"command\": \"xdebug-mcp\",\n      \"env\": {\n        \"XDEBUG_PORT\": \"9003\",\n        \"LOG_LEVEL\": \"info\"\n      }\n    }\n  }\n}\n```\n\n**Using npx:**\n\n```json\n{\n  \"mcpServers\": {\n    \"xdebug\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"xdebug-mcp\"],\n      \"env\": {\n        \"XDEBUG_PORT\": \"9003\",\n        \"LOG_LEVEL\": \"info\"\n      }\n    }\n  }\n}\n```\n\n### With Path Mappings (for Docker)\n\nWhen debugging PHP in Docker containers, you need path mappings to translate container paths to host paths:\n\n```json\n{\n  \"mcpServers\": {\n    \"xdebug\": {\n      \"command\": \"xdebug-mcp\",\n      \"env\": {\n        \"XDEBUG_PORT\": \"9003\",\n        \"PATH_MAPPINGS\": \"{\\\"/var/www/html\\\": \\\"/home/user/projects/myapp\\\"}\",\n        \"LOG_LEVEL\": \"info\"\n      }\n    }\n  }\n}\n```\n\n### With DBGp Proxy Registration\n\nIf you already use a DBGp proxy, keep [`mcp-config.example.json`](./mcp-config.example.json) as the default direct-listener example and start from [`mcp-config.proxy.example.json`](./mcp-config.proxy.example.json) for proxy registration.\n\nProxy mode requires:\n- TCP listener mode for `xdebug-mcp` (not `XDEBUG_SOCKET_PATH`)\n- a unique callback port such as `9006`, `9007`, or `9008` for `XDEBUG_PORT`\n- `DBGP_PROXY_HOST`, `DBGP_PROXY_PORT`, and `DBGP_IDEKEY`\n\nSee the [DBGp Proxy Registration Guide](./docs/_guides/dbgp-proxy-registration.md) for the full setup, multi-agent examples, and PHP/Xdebug proxy configuration.\n\n## PHP/Xdebug Configuration\n\n### php.ini (or xdebug.ini)\n\n```ini\n[xdebug]\nzend_extension=xdebug\n\n; Enable step debugging\nxdebug.mode=debug\n\n; Start debugging on every request\nxdebug.start_with_request=yes\n\n; Host where MCP server is running\n; For Docker: use host.docker.internal\n; For local PHP: use 127.0.0.1\nxdebug.client_host=host.docker.internal\n\n; Port where MCP server listens\nxdebug.client_port=9003\n\n; IDE key (optional, for filtering)\nxdebug.idekey=mcp\n```\n\n### Docker Compose\n\n```yaml\nversion: '3.8'\n\nservices:\n  php:\n    image: php:8.2-apache\n    volumes:\n      - ./src:/var/www/html\n      - ./xdebug.ini:/usr/local/etc/php/conf.d/99-xdebug.ini\n    extra_hosts:\n      - \"host.docker.internal:host-gateway\"  # Required for Linux\n    environment:\n      - XDEBUG_MODE=debug\n      - XDEBUG_CONFIG=client_host=host.docker.internal client_port=9003\n```\n\n### Using Unix Domain Sockets\n\nFor improved performance and simplified setup on local systems, you can use Unix domain sockets instead of TCP. Unix sockets eliminate network stack overhead and are ideal for debugging on the same machine.\n\n**Benefits:**\n- ⚡ Lower latency (no TCP/IP stack overhead)\n- 🔒 Better security (file permissions instead of port binding)\n- 📦 Simpler setup (no port management)\n- 🚀 Faster communication for local debugging\n\n**MCP Configuration (Unix Socket):**\n\n```json\n{\n  \"mcpServers\": {\n    \"xdebug\": {\n      \"command\": \"xdebug-mcp\",\n      \"env\": {\n        \"XDEBUG_SOCKET_PATH\": \"/tmp/xdebug.sock\",\n        \"LOG_LEVEL\": \"info\"\n      }\n    }\n  }\n}\n```\n\n**PHP/Xdebug Configuration:**\n\n```ini\n[xdebug]\nzend_extension=xdebug\nxdebug.mode=debug\nxdebug.start_with_request=yes\nxdebug.client_host=unix:///tmp/xdebug.sock\n```\n\n**Socket File Permissions:**\n\nThe socket file is created with default permissions. To restrict access, you can:\n\n```bash\n# After MCP server starts\nchmod 600 /tmp/xdebug.sock\n\n# Or use a secure directory\nmkdir -p ~/.xdebug && chmod 700 ~/.xdebug\n# Then set XDEBUG_SOCKET_PATH=$HOME/.xdebug/xdebug.sock\n```\n\n**Automatic Cleanup:**\n\nWhen `XDEBUG_SOCKET_PATH` is set, the server will:\n- Listen on the specified Unix socket instead of TCP port\n- Automatically clean up stale socket files on startup (prevents \"address in use\" errors)\n- Automatically clean up socket files on shutdown\n- Use the same debugging tools and features as TCP mode\n\n**When to Use Unix Sockets:**\n- ✅ Local PHP development (best performance)\n- ✅ Same-machine debugging\n- ✅ High-frequency breakpoint hits\n- ❌ Remote debugging (use TCP instead)\n\n*Unix socket support requested in [Issue #1](https://github.com/kpanuragh/xdebug-mcp/issues/1) by [@dkd-kaehm](https://github.com/dkd-kaehm)*\n\n## Available MCP Tools (41 Total)\n\n### Session Management\n\n| Tool | Description |\n|------|-------------|\n| `list_sessions` | List all active debug sessions |\n| `get_session_state` | Get detailed state of a session |\n| `set_active_session` | Set which session is active |\n| `close_session` | Close a debug session |\n\n### Breakpoints\n\n| Tool | Description |\n|------|-------------|\n| `set_breakpoint` | Set a line or conditional breakpoint (supports pending breakpoints) |\n| `set_exception_breakpoint` | Break on exceptions (supports pending breakpoints) |\n| `set_call_breakpoint` | Break on function calls (supports pending breakpoints) |\n| `remove_breakpoint` | Remove a breakpoint (works with pending breakpoints) |\n| `update_breakpoint` | Enable/disable or modify a breakpoint |\n| `list_breakpoints` | List all breakpoints including pending |\n\n**Pending Breakpoints**: You can set breakpoints before a debug session starts. These are stored as \"pending breakpoints\" and automatically applied when a PHP script connects with Xdebug. This is useful for setting up breakpoints before triggering a page load or script execution.\n\n### Execution Control\n\n| Tool | Description |\n|------|-------------|\n| `continue` | Continue to next breakpoint |\n| `step_into` | Step into function calls |\n| `step_over` | Step over (skip function internals) |\n| `step_out` | Step out of current function |\n| `stop` | Stop debugging |\n| `detach` | Detach and let script continue |\n\n### Inspection\n\n| Tool | Description |\n|------|-------------|\n| `get_stack_trace` | Get the call stack |\n| `get_contexts` | Get available variable contexts |\n| `get_variables` | Get all variables in scope |\n| `get_variable` | Get a specific variable |\n| `set_variable` | Set a variable's value |\n| `evaluate` | Evaluate a PHP expression |\n| `get_source` | Get source code |\n\n### Watch Expressions\n\n| Tool | Description |\n|------|-------------|\n| `add_watch` | Add a persistent watch expression |\n| `remove_watch` | Remove a watch expression |\n| `evaluate_watches` | Evaluate all watches and detect changes |\n| `list_watches` | List all active watches |\n\n### Logpoints\n\n| Tool | Description |\n|------|-------------|\n| `add_logpoint` | Add a logpoint with message template |\n| `remove_logpoint` | Remove a logpoint |\n| `get_logpoint_history` | View log output and hit statistics |\n\n### Profiling\n\n| Tool | Description |\n|------|-------------|\n| `start_profiling` | Start memory/time profiling |\n| `stop_profiling` | Stop profiling and get results |\n| `get_profile_stats` | Get current profiling statistics |\n| `get_memory_timeline` | View memory usage over time |\n\n### Code Coverage\n\n| Tool | Description |\n|------|-------------|\n| `start_coverage` | Start tracking code coverage |\n| `stop_coverage` | Stop and get coverage report |\n| `get_coverage_report` | View coverage statistics |\n\n### Debug Profiles\n\n| Tool | Description |\n|------|-------------|\n| `save_debug_profile` | Save current configuration as a profile |\n| `load_debug_profile` | Load a saved debug profile |\n| `list_debug_profiles` | List all saved profiles |\n\n### Additional Tools\n\n| Tool | Description |\n|------|-------------|\n| `capture_request_context` | Capture HTTP request context |\n| `add_step_filter` | Add filter to skip files during stepping |\n| `list_step_filters` | List step filter rules |\n| `get_function_history` | View function call history |\n| `export_session` | Export session as JSON/HTML report |\n| `capture_snapshot` | Capture debug state snapshot |\n\n## Usage Examples\n\n### Setting a Breakpoint\n\n```\nUse set_breakpoint with file=\"/var/www/html/index.php\" and line=25\n```\n\n### Conditional Breakpoint\n\n```\nUse set_breakpoint with file=\"/var/www/html/api.php\", line=42, condition=\"$userId > 100\"\n```\n\n### Watch Expression\n\n```\nUse add_watch with expression=\"$user->email\"\nUse add_watch with expression=\"count($items)\"\n```\n\n### Logpoint\n\n```\nUse add_logpoint with file=\"/var/www/html/api.php\", line=50, message=\"User {$userId} accessed {$endpoint}\"\n```\n\n### Inspecting Variables\n\n```\nUse get_variables to see all local variables\nUse get_variable with name=\"$user\" to inspect a specific variable\nUse evaluate with expression=\"count($items)\" to evaluate an expression\n```\n\n### Capture Request Context\n\n```\nUse capture_request_context to see $_GET, $_POST, $_SESSION, cookies, and headers\n```\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `XDEBUG_PORT` | `9003` | Port to listen for Xdebug connections (TCP mode) |\n| `XDEBUG_HOST` | `0.0.0.0` | Host to bind (TCP mode) |\n| `XDEBUG_SOCKET_PATH` | - | Unix domain socket path (e.g., `/tmp/xdebug.sock`). When set, uses Unix socket instead of TCP |\n| `COMMAND_TIMEOUT` | `30000` | Command timeout in milliseconds |\n| `PATH_MAPPINGS` | - | JSON object mapping container to host paths |\n| `MAX_DEPTH` | `3` | Max depth for variable inspection |\n| `MAX_CHILDREN` | `128` | Max children to return for arrays/objects |\n| `MAX_DATA` | `2048` | Max data size per variable |\n| `LOG_LEVEL` | `info` | Log level: debug, info, warn, error |\n\n## Connection Modes: TCP vs Unix Socket\n\n| Feature | TCP | Unix Socket |\n|---------|-----|-------------|\n| **Setup** | Easy (default) | Simple (one env var) |\n| **Performance** | Good | Excellent (lower latency) |\n| **Security** | Port accessible to network | File-based permissions |\n| **Remote Debugging** | ✅ Supported | ❌ Local only |\n| **Docker** | ✅ Works with host.docker.internal | ❌ Requires volume mount |\n| **Stale Socket** | Manual port cleanup | Auto-cleanup |\n| **Default** | `XDEBUG_PORT=9003` | Disabled (use TCP) |\n\n**Quick Decision Guide:**\n- 🏠 **Local development?** → Use Unix socket for best performance\n- 🐳 **Docker on same machine?** → Use Unix socket with volume mount\n- 🌐 **Remote server?** → Use TCP\n- 🚀 **Maximum speed?** → Use Unix socket\n- 📝 **Don't know?** → Start with TCP (default), switch to Unix socket if needed\n\n## How It Works\n\n1. **MCP Server starts** and listens for Xdebug connections (TCP port 9003 or Unix socket)\n2. **PHP script runs** with Xdebug enabled\n3. **Xdebug connects** to the MCP server via DBGp protocol\n4. **AI uses MCP tools** to control debugging (set breakpoints, step, inspect)\n5. **DBGp commands** are sent to Xdebug, responses parsed and returned\n\n```\n┌─────────────┐     MCP/stdio      ┌─────────────┐   DBGp/TCP or    ┌─────────────┐\n│   Claude    │ ◄────────────────► │  xdebug-mcp │ ◄─ Unix Socket ──► │   Xdebug    │\n│  (AI Agent) │                    │   Server    │                   │  (in PHP)   │\n└─────────────┘                    └─────────────┘                   └─────────────┘\n```\n\n**Connection Options:**\n- **TCP (Default):** `xdebug.client_host=127.0.0.1` + `XDEBUG_PORT=9003`\n- **Unix Socket:** `xdebug.client_host=unix:///tmp/xdebug.sock` + `XDEBUG_SOCKET_PATH=/tmp/xdebug.sock`\n\n## Troubleshooting\n\n### No debug sessions appearing\n\n1. Check that Xdebug is installed: `php -v` should show Xdebug\n2. Verify Xdebug config: `php -i | grep xdebug`\n3. Ensure `xdebug.client_host` points to the MCP server\n4. **For TCP:** Check firewall allows connections on port 9003\n5. **For Unix socket:** Verify socket path exists and has correct permissions: `ls -la /tmp/xdebug.sock`\n6. Check MCP server logs: `LOG_LEVEL=debug` for verbose output\n\n### Connection issues with Docker\n\n1. For Linux, add `extra_hosts: [\"host.docker.internal:host-gateway\"]`\n2. Verify container can reach host: `curl host.docker.internal:9003`\n3. Check xdebug logs in container: `docker logs <container-id> | grep xdebug`\n\n### Unix socket issues\n\n1. **\"Address already in use\"**: Socket file wasn't cleaned up\n   - Remove manually: `rm -f /tmp/xdebug.sock`\n   - MCP server will clean up automatically on next start\n2. **\"Permission denied\"**: Check socket file permissions\n   - List socket: `ls -la /tmp/xdebug.sock`\n   - Run as same user as PHP: `ps aux | grep php`\n3. **Socket path in php.ini:**\n   - Correct: `xdebug.client_host=unix:///tmp/xdebug.sock`\n   - Wrong: `xdebug.client_host=unix:/tmp/xdebug.sock` (missing one `/`)\n\n### Breakpoints not hitting\n\n1. Ensure file paths match exactly (use container paths for Docker)\n2. Check breakpoint is resolved: `list_breakpoints`\n3. Verify script execution reaches that line\n4. Check that `xdebug.start_with_request=yes` is set\n5. Try a simple file to verify basic setup works\n\n### Performance issues\n\n1. If experiencing slow stepping, increase `COMMAND_TIMEOUT`:\n   - Default: 30000ms (30 seconds)\n   - Try: `COMMAND_TIMEOUT=60000` for slower systems\n2. For Unix sockets, verify socket is on fast filesystem (not network mount)\n3. Check system load: `top` - excessive context switching slows debugging\n\n### Server won't start\n\n1. **Port in use (TCP):**\n   - Find process: `lsof -i :9003`\n   - Kill it: `kill -9 <pid>`\n2. **Bad config:**\n   - Validate environment variables: `echo $XDEBUG_SOCKET_PATH`\n   - Check for typos in path names\n3. **Permission denied:**\n   - For Unix socket, ensure write permission to parent directory\n   - Example: `mkdir -p ~/.xdebug && chmod 700 ~/.xdebug`\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT\n",
  "bytes": 15278,
  "sha": "8fbafe3cb87f1f981890c47f00435eb0429c27d37fd5341a4a690801c5ac750f",
  "repo_slug": "kpanuragh/xdebug-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kpanuragh_xdebug_273aa447/readme"
}