Xdebug

io.github.kpanuragh由 GitHub 帳號 kpanuragh 發布v1.2.1更新於 Oct 24, 2026

MCP server for PHP Xdebug debugging with breakpoints, stepping, and variable inspection

已驗證STDIO僅桌面開發者工具安全與監控

概覽

AI 產生的概覽

一個 MCP 伺服器,讓 AI 助理透過 Xdebug 的 DBGp 協定除錯 PHP 應用程式,支援中斷點、單步執行與變數檢視。

可以做什麼
  • 管理除錯工作階段:列出、檢視狀態、切換使用中的工作階段與關閉工作階段,可同時處理多個工作階段。
  • 設定、修改、移除與列出中斷點,包含行中斷點、條件中斷點、例外中斷點與函式呼叫中斷點,也支援待套用中斷點。
  • 控制執行:繼續、逐步進入、逐步跳過、逐步跳出、停止或分離。
  • 檢視狀態:呼叫堆疊、變數內容、變數、原始碼,並可求值 PHP 運算式或修改變數值。
  • 加入監看運算式與記錄點,並擷取 GET、POST、工作階段、Cookie 與請求標頭等請求內容。
  • 進行記憶體與耗時分析、追蹤程式碼涵蓋率、儲存與載入除錯設定,並將工作階段匯出為 JSON 或 HTML。
適用情境
適合在開發或排查 PHP 程式時,讓助理直接操作真實的除錯工作階段,而不是只憑原始碼推測;也適用於執行在 Docker 容器中或經 DBGp 代理的 PHP。
執行需求
以 npm 套件 xdebug-mcp 透過 stdio 在本機執行,需要 Node.js。PHP 需安裝 Xdebug 並啟用單步除錯,且指向伺服器的主機與連接埠。選用環境變數可設定連接埠、主機、Unix 通訊端路徑、路徑對應、逾時與記錄層級;代理模式需要 DBGP_PROXY_HOST、DBGP_PROXY_PORT 與 DBGP_IDEKEY。
安裝前請注意
伺服器會監聽除錯器連線;TCP 模式綁定的連接埠可從網路存取,本機使用建議改用 Unix 通訊端或限制綁定位址。工具可透過設定變數值改變程式狀態,逐步執行或繼續也會影響執行中的指令碼。通訊端檔案預設權限較寬鬆,需自行收緊。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Xdebug,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

Xdebug MCP Server

[npm version] [License: MIT]

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

Features

Core Debugging

  • Full Debug Control: Step into, step over, step out, continue, stop
  • Breakpoints: Line breakpoints, conditional breakpoints, exception breakpoints, function call breakpoints
  • Variable Inspection: View all variables, get specific variables, set variable values
  • Expression Evaluation: Evaluate PHP expressions in the current context
  • Stack Traces: View the full call stack
  • Multiple Sessions: Debug multiple PHP scripts simultaneously
  • Docker Support: Works with PHP running in Docker containers

Advanced Features

  • Watch Expressions: Persistent watches that auto-evaluate on each break with change detection
  • Logpoints: Log messages without stopping execution using {$var} placeholders
  • Memory Profiling: Track memory usage and execution time between breakpoints
  • Code Coverage: Track which lines were executed during debugging
  • Request Context: Capture $_GET, $_POST, $_SESSION, $_COOKIE, headers automatically
  • Step Filters: Skip vendor/library code during stepping
  • Debug Profiles: Save and restore breakpoint configurations
  • Session Export: Export debug sessions as JSON or HTML reports

Installation

From npm (Recommended)

bash
npm install -g xdebug-mcp

From Source

bash
git clone https://github.com/kpanuragh/xdebug-mcp.gitcd xdebug-mcpnpm installnpm run build

MCP Server Configuration

For Claude Code

Add the xdebug-mcp server to your MCP configuration (.mcp.json or Claude settings):

Using npm global install:

json
{  "mcpServers": {    "xdebug": {      "command": "xdebug-mcp",      "env": {        "XDEBUG_PORT": "9003",        "LOG_LEVEL": "info"      }    }  }}

Using npx:

json
{  "mcpServers": {    "xdebug": {      "command": "npx",      "args": ["-y", "xdebug-mcp"],      "env": {        "XDEBUG_PORT": "9003",        "LOG_LEVEL": "info"      }    }  }}

With Path Mappings (for Docker)

When debugging PHP in Docker containers, you need path mappings to translate container paths to host paths:

json
{  "mcpServers": {    "xdebug": {      "command": "xdebug-mcp",      "env": {        "XDEBUG_PORT": "9003",        "PATH_MAPPINGS": "{\"/var/www/html\": \"/home/user/projects/myapp\"}",        "LOG_LEVEL": "info"      }    }  }}

With DBGp Proxy Registration

If you already use a DBGp proxy, keep mcp-config.example.json as the default direct-listener example and start from mcp-config.proxy.example.json for proxy registration.

Proxy mode requires:

  • TCP listener mode for xdebug-mcp (not XDEBUG_SOCKET_PATH)
  • a unique callback port such as 9006, 9007, or 9008 for XDEBUG_PORT
  • DBGP_PROXY_HOST, DBGP_PROXY_PORT, and DBGP_IDEKEY

See the DBGp Proxy Registration Guide for the full setup, multi-agent examples, and PHP/Xdebug proxy configuration.

PHP/Xdebug Configuration

php.ini (or xdebug.ini)

ini
[xdebug]zend_extension=xdebug
; Enable step debuggingxdebug.mode=debug
; Start debugging on every requestxdebug.start_with_request=yes
; Host where MCP server is running; For Docker: use host.docker.internal; For local PHP: use 127.0.0.1xdebug.client_host=host.docker.internal
; Port where MCP server listensxdebug.client_port=9003
; IDE key (optional, for filtering)xdebug.idekey=mcp

Docker Compose

yaml
version: '3.8'
services:  php:    image: php:8.2-apache    volumes:      - ./src:/var/www/html      - ./xdebug.ini:/usr/local/etc/php/conf.d/99-xdebug.ini    extra_hosts:      - "host.docker.internal:host-gateway"  # Required for Linux    environment:      - XDEBUG_MODE=debug      - XDEBUG_CONFIG=client_host=host.docker.internal client_port=9003

Using Unix Domain Sockets

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

Benefits:

  • ⚡ Lower latency (no TCP/IP stack overhead)
  • 🔒 Better security (file permissions instead of port binding)
  • 📦 Simpler setup (no port management)
  • 🚀 Faster communication for local debugging

MCP Configuration (Unix Socket):

json
{  "mcpServers": {    "xdebug": {      "command": "xdebug-mcp",      "env": {        "XDEBUG_SOCKET_PATH": "/tmp/xdebug.sock",        "LOG_LEVEL": "info"      }    }  }}

PHP/Xdebug Configuration:

ini
[xdebug]zend_extension=xdebugxdebug.mode=debugxdebug.start_with_request=yesxdebug.client_host=unix:///tmp/xdebug.sock

Socket File Permissions:

The socket file is created with default permissions. To restrict access, you can:

bash
# After MCP server startschmod 600 /tmp/xdebug.sock
# Or use a secure directorymkdir -p ~/.xdebug && chmod 700 ~/.xdebug# Then set XDEBUG_SOCKET_PATH=$HOME/.xdebug/xdebug.sock

Automatic Cleanup:

When XDEBUG_SOCKET_PATH is set, the server will:

  • Listen on the specified Unix socket instead of TCP port
  • Automatically clean up stale socket files on startup (prevents "address in use" errors)
  • Automatically clean up socket files on shutdown
  • Use the same debugging tools and features as TCP mode

When to Use Unix Sockets:

  • ✅ Local PHP development (best performance)
  • ✅ Same-machine debugging
  • ✅ High-frequency breakpoint hits
  • ❌ Remote debugging (use TCP instead)

Unix socket support requested in Issue #1 by @dkd-kaehm

Available MCP Tools (41 Total)

Session Management

ToolDescription
list_sessionsList all active debug sessions
get_session_stateGet detailed state of a session
set_active_sessionSet which session is active
close_sessionClose a debug session

Breakpoints

ToolDescription
set_breakpointSet a line or conditional breakpoint (supports pending breakpoints)
set_exception_breakpointBreak on exceptions (supports pending breakpoints)
set_call_breakpointBreak on function calls (supports pending breakpoints)
remove_breakpointRemove a breakpoint (works with pending breakpoints)
update_breakpointEnable/disable or modify a breakpoint
list_breakpointsList all breakpoints including pending

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.

Execution Control

ToolDescription
continueContinue to next breakpoint
step_intoStep into function calls
step_overStep over (skip function internals)
step_outStep out of current function
stopStop debugging
detachDetach and let script continue

Inspection

ToolDescription
get_stack_traceGet the call stack
get_contextsGet available variable contexts
get_variablesGet all variables in scope
get_variableGet a specific variable
set_variableSet a variable's value
evaluateEvaluate a PHP expression
get_sourceGet source code

Watch Expressions

ToolDescription
add_watchAdd a persistent watch expression
remove_watchRemove a watch expression
evaluate_watchesEvaluate all watches and detect changes
list_watchesList all active watches

Logpoints

ToolDescription
add_logpointAdd a logpoint with message template
remove_logpointRemove a logpoint
get_logpoint_historyView log output and hit statistics

Profiling

ToolDescription
start_profilingStart memory/time profiling
stop_profilingStop profiling and get results
get_profile_statsGet current profiling statistics
get_memory_timelineView memory usage over time

Code Coverage

ToolDescription
start_coverageStart tracking code coverage
stop_coverageStop and get coverage report
get_coverage_reportView coverage statistics

Debug Profiles

ToolDescription
save_debug_profileSave current configuration as a profile
load_debug_profileLoad a saved debug profile
list_debug_profilesList all saved profiles

Additional Tools

ToolDescription
capture_request_contextCapture HTTP request context
add_step_filterAdd filter to skip files during stepping
list_step_filtersList step filter rules
get_function_historyView function call history
export_sessionExport session as JSON/HTML report
capture_snapshotCapture debug state snapshot

Usage Examples

Setting a Breakpoint

Use set_breakpoint with file="/var/www/html/index.php" and line=25

Conditional Breakpoint

Use set_breakpoint with file="/var/www/html/api.php", line=42, condition="$userId > 100"

Watch Expression

Use add_watch with expression="$user->email"Use add_watch with expression="count($items)"

Logpoint

Use add_logpoint with file="/var/www/html/api.php", line=50, message="User {$userId} accessed {$endpoint}"

Inspecting Variables

Use get_variables to see all local variablesUse get_variable with name="$user" to inspect a specific variableUse evaluate with expression="count($items)" to evaluate an expression

Capture Request Context

Use capture_request_context to see $_GET, $_POST, $_SESSION, cookies, and headers

Environment Variables

VariableDefaultDescription
XDEBUG_PORT9003Port to listen for Xdebug connections (TCP mode)
XDEBUG_HOST0.0.0.0Host to bind (TCP mode)
XDEBUG_SOCKET_PATH-Unix domain socket path (e.g., /tmp/xdebug.sock). When set, uses Unix socket instead of TCP
COMMAND_TIMEOUT30000Command timeout in milliseconds
PATH_MAPPINGS-JSON object mapping container to host paths
MAX_DEPTH3Max depth for variable inspection
MAX_CHILDREN128Max children to return for arrays/objects
MAX_DATA2048Max data size per variable
LOG_LEVELinfoLog level: debug, info, warn, error

Connection Modes: TCP vs Unix Socket

FeatureTCPUnix Socket
SetupEasy (default)Simple (one env var)
PerformanceGoodExcellent (lower latency)
SecurityPort accessible to networkFile-based permissions
Remote Debugging✅ Supported❌ Local only
Docker✅ Works with host.docker.internal❌ Requires volume mount
Stale SocketManual port cleanupAuto-cleanup
DefaultXDEBUG_PORT=9003Disabled (use TCP)

Quick Decision Guide:

  • 🏠 Local development? → Use Unix socket for best performance
  • 🐳 Docker on same machine? → Use Unix socket with volume mount
  • 🌐 Remote server? → Use TCP
  • 🚀 Maximum speed? → Use Unix socket
  • 📝 Don't know? → Start with TCP (default), switch to Unix socket if needed

How It Works

  1. MCP Server starts and listens for Xdebug connections (TCP port 9003 or Unix socket)
  2. PHP script runs with Xdebug enabled
  3. Xdebug connects to the MCP server via DBGp protocol
  4. AI uses MCP tools to control debugging (set breakpoints, step, inspect)
  5. DBGp commands are sent to Xdebug, responses parsed and returned
┌─────────────┐     MCP/stdio      ┌─────────────┐   DBGp/TCP or    ┌─────────────┐│   Claude    │ ◄────────────────► │  xdebug-mcp │ ◄─ Unix Socket ──► │   Xdebug    ││  (AI Agent) │                    │   Server    │                   │  (in PHP)   │└─────────────┘                    └─────────────┘                   └─────────────┘

Connection Options:

  • TCP (Default): xdebug.client_host=127.0.0.1 + XDEBUG_PORT=9003
  • Unix Socket: xdebug.client_host=unix:///tmp/xdebug.sock + XDEBUG_SOCKET_PATH=/tmp/xdebug.sock

Troubleshooting

No debug sessions appearing

  1. Check that Xdebug is installed: php -v should show Xdebug
  2. Verify Xdebug config: php -i | grep xdebug
  3. Ensure xdebug.client_host points to the MCP server
  4. For TCP: Check firewall allows connections on port 9003
  5. For Unix socket: Verify socket path exists and has correct permissions: ls -la /tmp/xdebug.sock
  6. Check MCP server logs: LOG_LEVEL=debug for verbose output

Connection issues with Docker

  1. For Linux, add extra_hosts: ["host.docker.internal:host-gateway"]
  2. Verify container can reach host: curl host.docker.internal:9003
  3. Check xdebug logs in container: docker logs <container-id> | grep xdebug

Unix socket issues

  1. "Address already in use": Socket file wasn't cleaned up
    • Remove manually: rm -f /tmp/xdebug.sock
    • MCP server will clean up automatically on next start
  2. "Permission denied": Check socket file permissions
    • List socket: ls -la /tmp/xdebug.sock
    • Run as same user as PHP: ps aux | grep php
  3. Socket path in php.ini:
    • Correct: xdebug.client_host=unix:///tmp/xdebug.sock
    • Wrong: xdebug.client_host=unix:/tmp/xdebug.sock (missing one /)

Breakpoints not hitting

  1. Ensure file paths match exactly (use container paths for Docker)
  2. Check breakpoint is resolved: list_breakpoints
  3. Verify script execution reaches that line
  4. Check that xdebug.start_with_request=yes is set
  5. Try a simple file to verify basic setup works

Performance issues

  1. If experiencing slow stepping, increase COMMAND_TIMEOUT:
    • Default: 30000ms (30 seconds)
    • Try: COMMAND_TIMEOUT=60000 for slower systems
  2. For Unix sockets, verify socket is on fast filesystem (not network mount)
  3. Check system load: top - excessive context switching slows debugging

Server won't start

  1. Port in use (TCP):
    • Find process: lsof -i :9003
    • Kill it: kill -9 <pid>
  2. Bad config:
    • Validate environment variables: echo $XDEBUG_SOCKET_PATH
    • Check for typos in path names
  3. Permission denied:
    • For Unix socket, ensure write permission to parent directory
    • Example: mkdir -p ~/.xdebug && chmod 700 ~/.xdebug

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

來源:README.md,提交 8e7b574

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v1.2.1最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分