DDEV MCP

A production-ready Model Context Protocol (MCP) server that provides AI assistants with DDEV development environment automation. Built with TypeScript using the official MCP SDK.

** 13 Essential Tools**

Streamlined tool set optimized for AI models. Supports all DDEV project types including Drupal, WordPress, Laravel, Symfony, TYPO3, CakePHP, Magento, and many more through the powerful ddev_exec command!

Complete DDEV Development Automation

This DDEV MCP server provides comprehensive development environment automation for any web project:

• Environment Management: Start, stop, restart DDEV projects
• Database Operations: Import/export, snapshots, migrations
• CMS-Specific Workflows: Drupal, WordPress, Laravel, etc

Documentation

• Tools reference — What each MCP tool does, arguments, and full ddev help output. Use this to see what the AI sees and how tools map to the DDEV CLI.

Features

Environment Management

• Start, stop, restart DDEV projects
• Get project status and detailed information
• Access container logs and SSH into services

Database Operations

• Import/export databases with various formats
• Support for compressed database files
• Target specific databases in multi-db setups

Command Executor (exec)

• Single ddev_exec tool handles all CMS/framework commands
• Drupal: Execute Drush commands (drush cr, drush cex, etc.)
• WordPress: WP-CLI commands (wp plugin list, wp core update, etc.)
• Laravel: Artisan commands (php artisan migrate, etc.)
• Symfony: Console commands (symfony console cache:clear, etc.)
• Composer: Package management (composer install, composer update, etc.)
• Redis, Solr, MySQL: Direct service commands
• Testing: Playwright, Cypress, PHPUnit, and custom test runners
• And more: Any command you can run in a DDEV container!

Production Ready

• Thorough error handling and logging
• Input validation and sanitization
• TypeScript for type safety
• Dangerous Command Protection: Built-in safety system for production-affecting commands

Installation

Prerequisites

• Node.js 20+ (Node.js 22+ preferred for best performance)
• DDEV installed and available in PATH
• TypeScript knowledge for team contributions

Quick Setup

# Install globally
npm install -g ddev-mcp

# Or run directly with npx
npx ddev-mcp --help

# Verify installation
ddev-mcp --version

Node.js Version Requirements

• Minimum: Node.js 20.0.0+
• Recommended: Node.js 22.0.0+ (for best performance and latest features)
• Check your version: node --version

Development Setup

git clone git@github.com:codingsasi/ddev-mcp.git
cd ddev-mcp
npm install
npm run build
npm run dev

Configuration

MCP Client Configuration

Add to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ddev": {
      "command": "npx",
      "args": ["ddev-mcp"],
      "env": {
        "ALLOW_DANGEROUS_COMMANDS": "false" // true if you want ddev to run commands like `platform redeploy -emaster`
      },
    }
  }
}

No additional configuration needed! The server automatically detects your DDEV projects.

Environment Variables

# Optional: Configure logging level
export DDEV_MCP_LOG_LEVEL="DEBUG"

# Optional: Max buffer size in bytes for command output (default: 2097152 = 2 MiB).
# If a command's stdout+stderr exceeds this, Node throws ERR_CHILD_PROCESS_STDIO_MAXBUFFER.
export DDEV_MCP_MAX_BUFFER="4194304"

# Safety: Allow dangerous commands (default: false)
export ALLOW_DANGEROUS_COMMANDS="true"

Dangerous Command Protection

The DDEV MCP server includes built-in protection against dangerous commands that could affect production environments:

• Platform.sh commands like environment:redeploy, environment:delete are blocked by default
• Database operations that could delete data are protected
• File operations that could remove important files are safeguarded

Enabling Dangerous Commands

To allow dangerous commands (use with caution):

export ALLOW_DANGEROUS_COMMANDS="true"

Adding New Dangerous Commands

Contributors can easily add dangerous command patterns in src/config/dangerous-commands.ts. See DANGEROUS_COMMANDS.md for detailed instructions.

Simple Directory Handling

The DDEV MCP server operates on the current working directory principle:

• Runs commands in whatever directory the MCP server is invoked from
• No complex directory detection or configuration needed
• User controls the context by navigating to the correct directory

CMS-Specific Development Usage (via ddev_exec)

# Drupal
"Use ddev mcp to clear Drupal cache"
"Use ddev mcp to execute drush cex to export configuration"
"Use ddev mcp to use drush uli to get a one-time login link"

# WordPress
"Use ddev mcp to install and activate the Akismet plugin with wp plugin install"
"ddev mcp: Run wp core update to update WordPress"
"ddev mcp: Run wp cache flush to clear caches"

# Composer
"Use ddev mcp to run composer install using ddev_exec"
"ddev mcp: Update packages with composer update"

Other things you can do

"DDEV MCP: Start fresh development environment with latest DB"
"DDEV MCP: Enable debug mode and clear cache for debugging"
"DDEV MCP: Import test data for testing"

# Add-on specific workflows (via ddev_exec)
"DDEV MCP: Clear Redis cache with redis-cli FLUSHALL"
"DDEV MCP: Check Redis memory with redis-cli INFO memory"
"DDEV MCP: Query Solr with curl commands"
"DDEV MCP: Run MySQL queries with mysql -e"
"DDEV MCP: Execute Playwright tests"

# Directory navigation workflows
"DDEV MCP: Go to my WordPress project at ~/Projects/mysite and start it"
"DDEV MCP: Navigate to /home/user/drupal-site directory and check project status"
"DDEV MCP: Go to the correct project folder and run database import"

Available Tools

Project management (start, stop, restart, describe, list, logs), database (import, export, snapshots), ddev_exec for any in-container command (Drush, WP-CLI, Composer, etc.), plus ddev_help, ddev_version, ddev_poweroff, and message_complete_notification. Full list with arguments and ddev help output: Tools reference.

Development & Testing

Build and Test

• Clone the repo to /path/to/repo/for/ddev-mcp/
• Run npm run build
• and add the following to mcp.json file.

{
  "mcpServers": {
    "ddev": {
      "command": "npx",
      "args": [
        "/path/to/repo/for/ddev-mcp/dist/index.js"
      ],
      "env": {
        "DDEV_MCP_LOG_LEVEL": "INFO"
      },
    },
  }
}

Architecture

Project Structure

src/
├── server/          # MCP server implementation
│   ├── index.ts     # Main server class
│   └── tools.ts     # Tool definitions and validation
├── ddev/            # DDEV operations
│   └── operations.ts # Core DDEV command implementations
├── utils/           # Utilities
│   ├── logger.ts    # Structured logging
│   └── command.ts   # Safe command execution
├── types/           # TypeScript definitions
│   └── index.ts     # Type definitions
└── index.ts         # CLI entry point

Contributing

This project is designed for team collaboration with familiar JavaScript/TypeScript patterns:

1. Fork and Clone: Standard GitHub workflow
2. Install Dependencies: npm install
3. Build: npm run build
4. Make Changes: Follow existing patterns
5. Test: Manually (Use it in your ddev project)
6. Submit PR: With clear description

Coding Standards

• TypeScript strict mode enabled
• ESLint configuration for consistency
• Comprehensive error handling
• Unit tests for new features
• Documentation updates

🙏 Acknowledgments

• Built with the official Model Context Protocol SDK
• Designed for DDEV development environments

External Resources

• DDEV CMS Quickstarts - Official DDEV project type documentation
• DDEV Documentation - Local development environment guide

Ready to supercharge your DDEV development workflow with AI assistance for any web project! 🚀