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:

⚠️ 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:

Option 2: NPM Installation (Currently Unavailable)

Option 3: Build from Source

Option 4: Quick Installation Script

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

Local Installation

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)

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)

Multi-Project Mode (Flexible for multiple projects)

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)

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:

Usage Examples

Project Targeting Options

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

Single Project Mode (Single Project Configured)

All commands automatically target the configured single project.

Multi-Project Mode (No Single Project Restriction)

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

Verify Installation

Requirements

• Node.js 20+

• DDEV installed and accessible via PATH

• DDEV projects configured

Development

Building and Running

Code Quality

Testing