Skip to content

Getting Started

Jump to bottom
Anuragh K P edited this page Mar 23, 2026 · 1 revision

Getting Started

Welcome! This guide will help you set up the Xdebug MCP Server in just a few minutes.

Prerequisites

  • Node.js 18.0.0 or higher
  • npm or yarn
  • PHP 7.0+ with Xdebug extension
  • Basic command line knowledge

Installation

Step 1: Install Xdebug MCP Server

npm install -g xdebug-mcp

Or using yarn:

yarn global add xdebug-mcp

Step 2: Verify Installation

xdebug-mcp --version

Expected output:

xdebug-mcp v1.2.1

Setting Up PHP

Install Xdebug Extension

Using PECL (Recommended):

pecl install xdebug

Ubuntu/Debian:

sudo apt-get install php-xdebug

macOS (Homebrew):

brew install php-xdebug

Windows: Download from xdebug.org/download

Configure php.ini

Find your php.ini file:

php --ini

Add Xdebug configuration:

[xdebug]
zend_extension=xdebug

; Enable debug mode
xdebug.mode=debug

; Connection settings
xdebug.client_host=localhost
xdebug.client_port=9003

; IDE Key (identifier)
xdebug.idekey=xdebug-mcp

; Logging (optional)
xdebug.log=/tmp/xdebug.log
xdebug.log_level=10

Verify Xdebug Installation

php -v | grep Xdebug

Should output:

with Xdebug X.X.X

Quick Start

1. Start the MCP Server

xdebug-mcp

Expected output:

[INFO] Xdebug MCP Server listening on localhost:9003
[INFO] Server ready for debugging

2. Create a Test Script

Save as test.php:

<?php
function greet($name) {
    $message = "Hello, " . $name;
    return $message;
}

$result = greet("World");
echo $result;

3. Debug the Script

php test.php

The script will pause at breakpoints when you set them via the MCP client.

Using with Claude

Once the MCP Server is running, configure your MCP client to connect:

{
  "mcpServers": {
    "xdebug": {
      "command": "xdebug-mcp"
    }
  }
}

Then use Claude with the debugging tools!

Connection Modes

TCP Mode (Default)

Works out of the box on all platforms:

xdebug-mcp
# Listens on localhost:9003

Unix Socket Mode (Faster)

For Linux/macOS:

XDEBUG_SOCKET_PATH=/tmp/xdebug.sock xdebug-mcp

Update php.ini:

xdebug.client_host=/tmp/xdebug.sock
xdebug.client_port=0

Docker Setup

Docker Compose Example

version: '3'
services:
  app:
    image: php:8.1-cli
    volumes:
      - ./app:/app
    working_dir: /app
    command: php app.php

  debugger:
    image: node:18
    command: npm install -g xdebug-mcp && xdebug-mcp
    ports:
      - "9003:9003"

Run with:

docker-compose up

Troubleshooting First Steps

"Command not found: xdebug-mcp"

Make sure npm is in your PATH:

npm list -g xdebug-mcp

If not installed, reinstall:

npm install -g xdebug-mcp

"Port 9003 already in use"

Use a different port:

XDEBUG_PORT=9004 xdebug-mcp

Update php.ini:

xdebug.client_port=9004

"Xdebug not connecting"

  1. Check php.ini:
php -i | grep -i xdebug
  1. Check Xdebug log:
tail -f /tmp/xdebug.log
  1. Verify server listening:
lsof -i :9003

Environment Variables

Configure server behavior with environment variables:

# TCP mode (default)
XDEBUG_HOST=0.0.0.0
XDEBUG_PORT=9003

# Unix socket mode
XDEBUG_SOCKET_PATH=/tmp/xdebug.sock

# Logging
DEBUG=xdebug-mcp

File Structure

After installation, you'll have:

~/.npm-global/lib/node_modules/xdebug-mcp/
├── dist/
│   ├── index.js
│   ├── config.js
│   └── ...
├── package.json
└── README.md

Next Steps

  1. Read Debugging Guide - Learn how to debug PHP code
  2. Explore Understanding Xdebug - Understand how Xdebug works
  3. Check Tools & Commands - See what debugging tools are available
  4. Setup Connection Modes - Choose TCP or Unix socket

Getting Help

System Requirements

Component Requirement
Node.js 18.0.0+
PHP 7.0+
Xdebug 2.9+ or 3.0+
OS Linux, macOS, Windows
RAM 100MB minimum
Disk 50MB

Quick Reference

# Install
npm install -g xdebug-mcp

# Start server
xdebug-mcp

# TCP mode on custom port
XDEBUG_PORT=9004 xdebug-mcp

# Unix socket mode
XDEBUG_SOCKET_PATH=/tmp/xdebug.sock xdebug-mcp

# Debug mode (verbose logging)
DEBUG=xdebug-mcp xdebug-mcp

# Stop server
Ctrl+C

What's Next?

You're all set! 🎉

  1. Start the server: xdebug-mcp
  2. Configure PHP with Xdebug
  3. Create a test script
  4. Set breakpoints and debug!

Have questions? Check the Troubleshooting page or visit the GitHub repository.

Clone this wiki locally