XdebugCAUTION
MCP server for PHP Xdebug debugging - enables AI-assisted PHP debugging through the Model Context Protocol with Unix socket and TCP support
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](https://www.npmjs.com/package/xdebug-mcp) [](https://opensource.org/licenses/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)
npm install -g xdebug-mcp
From Source
git clone https://github.com/kpanuragh/xdebug-mcp.git cd xdebug-mcp npm install npm 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 instal
3e33a4dea921OBSERVED · 2026-10-09Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add xdebug-mcp -- npx -y [email protected]
Exposed tools (46)
27 read · 14 write · 5 destructive. Blast radius: 5 tools can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
add_logpoint | write | Add a logpoint that logs messages without stopping execution. Use {varName} placeholders for variables. |
add_step_filter | write | Add a step filter to skip certain files/directories during stepping (e.g., vendor code) |
add_watch | write | Add a watch expression that will be evaluated on each break. Watch expressions persist across steps. |
capture_request_context | read | Capture the current HTTP request context ($_GET, $_POST, $_SESSION, $_COOKIE, headers) |
capture_snapshot | read | Capture a snapshot of the current debug state for the export report |
close_session | destructive | Close and terminate a debug session |
continue | read | Continue script execution until the next breakpoint or end of script |
detach | read | Detach from the debug session and let the script continue running without debugging |
evaluate | read | Evaluate a PHP expression in the current context. Returns the result of the expression. Use for calculations, method calls, or inspecting computed values. |
evaluate_watches | read | Evaluate all watch expressions and return their current values |
export_session | read | Export the current debug session as a report |
get_contexts | read | Get available variable contexts (Local, Superglobals, User-defined constants) at the current position |
get_coverage_report | read | Get the current code coverage report |
get_function_history | read | Get the history of function calls made during debugging |
get_logpoint_history | read | Get the log output history from logpoints |
get_memory_timeline | read | Get memory usage timeline from profiling |
get_profile_stats | read | Get current profiling statistics |
get_session_state | read | Get detailed state of a specific debug session including current position and status |
get_source | read | Get the source code of a file or a specific line range |
get_stack_trace | read | Get the current call stack showing all function calls leading to the current position |
get_variable | read | Get a specific variable by name, including nested properties. Use PHP syntax for nested access (e.g., |
get_variables | read | List all variables in scope with metadata (names, types, child counts). Use get_variable() to inspect specific variable values. Returns lightweight metadata for browsing the variable tree. |
list_breakpoints | read | List all breakpoints including both active session breakpoints and pending breakpoints |
list_debug_profiles | read | List all saved debug profiles |
list_sessions | read | List all active PHP debug sessions with their current state |
list_step_filters | read | List all step filter rules |
list_watches | read | List all active watch expressions |
load_debug_profile | read | Load a saved debug profile |
remove_breakpoint | destructive | Remove a breakpoint by its ID. Works for both active session breakpoints and pending breakpoints. |
remove_logpoint | destructive | Remove a logpoint |
remove_watch | destructive | Remove a watch expression |
save_debug_profile | write | Save the current debug configuration (breakpoints, watches, filters) as a named profile |
set_active_session | write | Set which debug session should be the active/default session for subsequent commands |
set_breakpoint | write | Set a breakpoint in PHP code. Supports line breakpoints and conditional breakpoints with hit counts. Can be set before a debug session starts - breakpoints will be applied when a session connects. |
set_call_breakpoint | write | Set a breakpoint that triggers when a specific function is called. Can be set before a debug session starts. |
set_exception_breakpoint | write | Set a breakpoint that triggers when a specific exception is thrown. Can be set before a debug session starts. |
set_variable | write | Set the value of a variable in the current scope |
start_coverage | write | Start tracking code coverage during debugging |
start_profiling | write | Start profiling to track memory usage and execution time |
step_into | read | Step into the next function call, or to the next line if not a function call. This follows execution into called functions. |
step_out | read | Step out of the current function. Execution continues until the current function returns. |
step_over | read | Step over to the next line in the current scope. Function calls are executed but not stepped into. |
stop | destructive | Stop the debug session and terminate script execution immediately |
stop_coverage | write | Stop tracking code coverage and get the report |
stop_profiling | write | Stop profiling and get the results |
update_breakpoint | write | Update a breakpoint (enable/disable or change hit conditions). Works for both active session and pending breakpoints. |
Trust audit
CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | WARN |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (1 observation(s))
- Network
- none-observed
- Shell
- none-observed
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (3)
if (ms < 1) return `${(ms * 1000).toFixed(2)} μs`;close_session, remove_breakpoint, remove_logpoint, remove_watch, stop
@modelcontextprotocol/sdk, fast-xml-parser, zod, @types/node, typescript, tsx
Gates applied: no_behavioural_pass.
3e33a4dea921full audit observations/trust-audit/mcp-server/kpanuragh__xdebug.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-09 | 3e33a4dea921 | CAUTION | B | 89 | first audit |
Questions
What is the Xdebug MCP server?
MCP server for PHP Xdebug debugging - enables AI-assisted PHP debugging through the Model Context Protocol with Unix socket and TCP support
What tools does Xdebug expose?
46 in total: 27 read-only, 14 that write, and 5 that can delete or overwrite (close_session, remove_breakpoint, remove_logpoint, remove_watch, stop). Every one is listed on this page with its risk.
Is Xdebug safe to connect to an agent?
With care. The audit graded it B (89/100) and found 3 things worth knowing before you trust this server, listed below with the exact line each was found on. Separately from the audit: 5 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does Xdebug need?
It reads DBGP_IDEKEY from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does Xdebug run?
It speaks stdio, so it runs as a local process your client starts. It is published on npm as xdebug-mcp at 1.3.1.
How current is this page?
The grade is for one exact copy of the source (3e33a4dea921), read on 2026-10-09. The repository is watched and re-audited when it changes.