AkibaAT/ddev-mcp

DDEV MCP Server

Overview

This project provides a Model Context Protocol (MCP) server that enables Large Language Models (LLMs) and AI assistants to interact with DDEV local development environments.

Features include:

• 🗄️ Query databases directly - Execute SQL queries, inspect schemas, and analyze data in your DDEV MySQL/PostgreSQL databases
• 🚀 Manage DDEV projects - Start, stop, restart projects and check their status
• 🔧 Execute development commands - Run Composer, access logs, control Xdebug, and execute shell commands in containers
• 🛡️ Maintain security - Whitelist-based protection ensures only safe operations are allowed by default

Use Cases:

• Database Development: "Show me all users with pending orders" → LLM queries your local database directly
• Debugging: "Check the error logs for the last hour" → LLM retrieves and analyzes DDEV service logs
• Project Management: "Start my e-commerce project and check if the database is ready" → LLM manages your DDEV environment
• Schema Analysis: "What's the relationship between users and orders tables?" → LLM inspects your actual database structure
• Development Workflow: "Run the latest migrations and show me the updated schema" → LLM executes commands and verifies results

Features

Tools

Database Operations

• ddev_db_backup - Create database snapshots
• ddev_db_describe_table - Get table structure/schema (PostgreSQL \d or MySQL DESCRIBE)
• ddev_db_list_backups - List available database backups
• ddev_db_list_databases - List all databases (PostgreSQL \l or MySQL SHOW DATABASES)
• ddev_db_list_tables - List all tables in the database (auto-detects database type)
• ddev_db_query - Execute SQL queries with detailed error reporting (supports PostgreSQL, MySQL, MariaDB)
• ddev_db_restore - Restore from database snapshots

Project Management

• ddev_list_projects - List all DDEV projects with status
• ddev_project_status - Get current status and configuration of a DDEV project
• ddev_start_project - Start a DDEV project
• ddev_stop_project - Stop a DDEV project
• ddev_restart_project - Restart a DDEV project

DDEV Service Operations

• ddev_exec_command - Execute commands in DDEV web service
• ddev_exec_service - Execute commands in specific DDEV services (web, db, redis, etc.)
• ddev_ssh - SSH access and connection information
• ddev_logs - Get service logs

Development Tools

• ddev_composer_command - Run Composer commands
• ddev_xdebug - Control Xdebug (on/off/toggle/status)
• ddev_share - Share project via ngrok tunnel
• ddev_mailpit - Access Mailpit for email testing

Database Management

• ddev_export_db - Export database dumps
• ddev_import_db - Import database dumps

🔒 Security Features:

• Whitelist Security Model: Only explicitly allowed read-only operations are permitted (default deny)
• Comprehensive Protection: Blocks hundreds of potentially dangerous operations by default
• Write Protection: All data modification blocked by default unless --allow-write is used
• Catastrophic Operation Blocking: DROP DATABASE, SHUTDOWN, file operations always blocked
• Configuration Protection: Blocks SET, FLUSH, GRANT, and other config changes

Resources

• ddev://current - Current project context and server configuration
• ddev://config - Current project DDEV configuration

Security Features

🔒 Whitelist Security Model (Default Deny) The MCP server uses a comprehensive whitelist approach where only explicitly allowed read-only operations are permitted. Any query not matching the whitelist is automatically blocked.

✅ Allowed Operations (Whitelist)

• SELECT - Data queries and joins
• SHOW - Database/table inspection (TABLES, DATABASES, COLUMNS, etc.)
• DESCRIBE / DESC - Table structure
• EXPLAIN - Query execution plans
• WITH ... SELECT - Common Table Expressions (read-only)
• PostgreSQL meta-commands (\dt, \d, \l, etc.)
• System catalog queries (INFORMATION_SCHEMA, pg_catalog)

🚫 Always Blocked (Even with --allow-write)

• DROP DATABASE / DROP SCHEMA - Catastrophic deletions
• SHUTDOWN, KILL - System control
• File system access (LOAD_FILE, INTO OUTFILE)
• Shell commands (\!, COPY ... FROM PROGRAM)
• Other system-level operations

Enabling Write Operations

To enable write operations, use the --allow-write flag:

# Enable write operations
ddev-mcp --allow-write

# Enable write operations with single project mode
ddev-mcp --allow-write --single-project my-project

⚠️ Warning: Only enable write operations when necessary and ensure you trust the LLM application accessing the server.

Multi-Database Support

The MCP server automatically detects the database type from your DDEV configuration and uses the appropriate commands:

PostgreSQL Projects

• Commands: psql, \dt, \d table_name, \l
• Detected from: database.type: postgres in .ddev/config.yaml

MySQL/MariaDB Projects

• Commands: mysql, SHOW TABLES, DESCRIBE table_name, SHOW DATABASES
• Detected from: database.type: mysql or database.type: mariadb in .ddev/config.yaml

Automatic Detection

• Reads .ddev/config.yaml to determine database type
• Falls back to MySQL if no configuration found
• Database type is shown in command output for clarity

Installation & Deployment

Option 1: Download from GitHub Releases (Recommended)

Download the NPM package from the latest release and install locally:

# Download the .tgz file from releases, then:
npm install -g ./ddev-mcp-0.8.0.tgz

# Verify installation
ddev-mcp --help

Option 2: NPM Installation (Currently Unavailable)

# NPM publishing is currently disabled
# Use Option 1 (GitHub Releases) instead
npm install -g ddev-mcp  # This will not work currently

# Or install directly from the downloaded package
tar -xzf ddev-mcp-1.0.0.tgz
cd package
npm install -g .

Option 3: Build from Source

# Clone the repository
git clone https://github.com/AkibaAT/ddev-mcp.git
cd ddev-mcp

# Install dependencies and build
npm install
npm run build

# Install globally (optional)
npm install -g .

Option 4: Quick Installation Script

# Clone and install
git clone https://github.com/AkibaAT/ddev-mcp.git
cd ddev-mcp
chmod +x install.sh
./install.sh

This will:

• ✅ Check system requirements (Node.js 20+, DDEV)
• 📦 Install the server globally via npm
• 📋 Provide MCP client configuration

MCP Client Configuration

Basic Configuration

Global Installation

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

Local Installation

{
  "mcpServers": {
    "ddev": {
      "command": "node",
      "args": ["/absolute/path/to/ddev-mcp/dist/index.js"]
    }
  }
}

Advanced Configuration with Single Project Mode

⚠️ Important: When you configure single project mode, the MCP server becomes limited to that single project only. All tools will automatically target the configured project, project selection parameters (project_name) will be hidden from the interface, and the ddev_list_projects command will be disabled for security reasons (to prevent information disclosure about other projects on the system).

Single Project Mode (Recommended for dedicated development)

{
  "mcpServers": {
    "ddev": {
      "command": "ddev-mcp",
      "args": ["--single-project", "project-id"]
    }
  }
}

Use Case: Perfect when working on a single project and you want a clean, dedicated interface without repetitive project parameters.

Enable Write Operations (Use with Caution)

{
  "mcpServers": {
    "ddev-write": {
      "command": "ddev-mcp",
      "args": ["--allow-write", "--single-project", "development-site"]
    }
  }
}

Multi-Project Mode (Flexible for multiple projects)

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

Use Case: When working with multiple DDEV projects, you can specify project_name or project_path for each command. All tools will show project selection parameters.

Multiple Dedicated Servers (Different projects and security levels)

{
  "mcpServers": {
    "ddev-production": {
      "command": "ddev-mcp",
      "args": ["--single-project", "main-site"]
    },
    "ddev-development": {
      "command": "ddev-mcp",
      "args": ["--allow-write", "--single-project", "dev-site"]
    }
  }
}

Use Case: Separate MCP servers for different projects with different security levels (e.g., read-only for production, write-enabled for development).

Configuration Summary

Configuration File Locations

Configuration file locations depend on your MCP client. Common examples:

• Generic MCP Client: ~/.config/mcp/config.json
• Application-specific: Check your MCP client documentation for the correct path

Project Context Features

🎯 Intelligent Project Context When you configure single project mode, the MCP server provides rich contextual information to LLMs through the ddev://current resource.

Current Project Information

The ddev://current resource provides real-time:

• Project Details: Name, status, database type, URL
• Server Configuration: Security mode, default settings
• Dynamic Status: Current project state (updated when accessed)

Example Response:

{
  "project": {
    "name": "project-id",
    "status": "running", 
    "dbType": "postgres",
    "url": "https://project-id.ddev.site",
    "description": "DDEV project 'project-id' (running) using postgres database"
  },
  "serverConfig": {
    "securityMode": "read-only",
    "allowWriteOperations": false
  }
}

Usage Examples

Project Targeting Options

The MCP server supports different project targeting modes depending on your configuration:

Single Project Mode (Single Project Configured)

// Clean interface - no project parameters needed or visible
{
  "name": "ddev_db_query",
  "arguments": {
    "query": "SELECT COUNT(*) FROM games;"
  }
}

All commands automatically target the configured single project.

Multi-Project Mode (No Single Project Restriction)

// Use Project Name
{
  "name": "ddev_db_query",
  "arguments": {
    "project_name": "project-id",
    "query": "SELECT COUNT(*) FROM users;"
  }
}

// Start a specific project
{
  "name": "ddev_start_project", 
  "arguments": {
    "project_name": "my-site"
  }
}

Project parameters are visible and required for targeting specific projects.

Project Resolution (Multi-Project Mode Only)

When no single project restriction is configured, the server resolves projects in this order:

1. Explicit project_name - Uses the specified DDEV project name
2. Current directory - Fallback if no project name provided

Note: In single project mode, all commands automatically use the configured project.

Testing & Debugging

Test with MCP Inspector

# Global installation
npx @modelcontextprotocol/inspector ddev-mcp

# Local installation
npx @modelcontextprotocol/inspector node dist/index.js

# Development mode
npx @modelcontextprotocol/inspector node --loader ts-node/esm index.ts

Verify Installation

# Check if globally installed
which ddev-mcp

# Test DDEV integration
ddev list --json-output

Requirements

• Node.js 20+
• DDEV installed and accessible via PATH
• DDEV projects configured

Development

Building and Running

npm run dev         # Run with ts-node
npm run build       # Build TypeScript
npm run start       # Run built version

Code Quality

npm run lint        # Run ESLint
npm run lint:fix    # Fix auto-fixable ESLint issues
npm run lint:check  # Run ESLint with strict checking (CI)

Testing

npm run test        # Run tests
npm run test:watch  # Run tests in watch mode
npm run test:ci     # Run tests for CI (with coverage)