Skip to main content
Glama

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

Related MCP server: Webasyst MCP Server

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


External Resources

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

Available Tools

14 tools
ddev_describeA

Get a detailed description of a running DDEV project (name, location, URL, status, MySQL connection details, Mailpit, etc.). Aliases: describe, status, st. Usage: ddev describe [projectname] [flags] For full options: ddev help describe

Inputs: projectPath.

ddev_execA

Execute a shell command in the container for a DDEV service. Default: web service; use service (e.g. db, redis, solr) to run in another. workdir maps to ddev --dir. Usage: ddev exec [flags] [command] [command-flags] Flags: -s/--service (default web), -d/--dir (execution directory) For full options: ddev help exec

COMMON USE CASES:

Drupal (Drush):

  • "drush status" - Site status

  • "drush cr" - Clear cache

  • "drush uli" - Generate login link

  • "drush cex" - Export config

  • "drush cim" - Import config

  • "drush pm:install module_name" - Install module

  • "drush updb -y" - Run database updates

WordPress (WP-CLI):

  • "wp cli version" - WP-CLI version

  • "wp plugin list" - List plugins

  • "wp plugin install akismet --activate" - Install & activate plugin

  • "wp theme list" - List themes

  • "wp user list" - List users

  • "wp core update" - Update WordPress

  • "wp cache flush" - Clear cache

  • "wp search-replace old.com new.com" - Search/replace URLs

Composer:

  • "composer install" - Install dependencies

  • "composer update" - Update packages

  • "composer require vendor/package" - Add package

  • "composer show" - List installed packages

Redis:

  • "redis-cli INFO" - Server info

  • "redis-cli PING" - Test connection

  • "redis-cli KEYS *" - List keys

  • "redis-cli FLUSHALL" - Clear all caches

Solr:

MySQL/MariaDB:

  • "mysql -e 'SHOW DATABASES'" - List databases

  • "mysql -e 'SHOW TABLES' db" - List tables

  • "mysql -e 'SELECT VERSION()'" - Database version

Platform.sh CLI:

  • "platform environment:list" - List environments

  • "platform db:dump" - Export database

Node.js/npm:

  • "npm install" - Install packages

  • "npm run build" - Build assets

  • "npm run test" - Run tests

  • "node --version" - Node version

Testing Frameworks:

  • "playwright test" - Run Playwright tests

  • "cypress run" - Run Cypress tests

  • "phpunit" - Run PHP unit tests

Other:

  • "php -v" - PHP version

  • "ls -la" - List files

  • "cat config/sync/system.site.yml" - Read file

  • "env" - Show environment variables

Dangerous commands blocked unless ALLOW_DANGEROUS_COMMANDS=true.

Inputs: command (required), projectPath (required), service, workdir.

ddev_export_dbA

Dump a database to a file or stdout. Compression: gzip (default), bzip2, or xz. Target DB via targetDb (default "db"). Usage: ddev export-db [project] [flags] MCP args → ddev: file → -f/--file, targetDb → -d/--database, compressionType → --gzip|--bzip2|--xz For full options and examples: ddev help export-db

Inputs: file, targetDb, projectPath, compressionType.

ddev_helpA

Get help for any DDEV command. Returns the same output as "ddev help " or "ddev --help". Use when you need exact flags, examples, or usage for a ddev command. Usage: ddev help [command] | ddev --help Examples: command="import-db" → ddev help import-db; command="snapshot", subcommand="restore" → ddev snapshot restore --help. Leave command empty for general ddev help.

Inputs: command, subcommand, projectPath.

ddev_import_dbA

Import a SQL dump file into the project. Supports .sql, .sql.gz, .sql.bz2, .sql.xz, .mysql, .zip, .tgz, .tar.gz. For archives, use extractPath for path inside archive. Target DB via targetDb (default "db"). Usage: ddev import-db [project] [flags] MCP args → ddev: src → --file, targetDb → --database, extractPath → --extract-path For full options and examples: ddev help import-db

Inputs: src, targetDb, extractPath, projectPath.

ddev_listA

List DDEV projects and their status. Shows all by default; use activeOnly for running only. Usage: ddev list [flags] Flags: -A/--active-only, -t/--type For full options: ddev help list

Inputs: activeOnly.

ddev_logsA

Display stdout logs from DDEV services (docker logs). Default: web service; use service for e.g. db. Usage: ddev logs [projectname] [flags] Flags: -s/--service (web|db), -f/--follow, --tail N For full options: ddev help logs

Inputs: tail, follow, service, projectPath.

ddev_poweroffA

Stop all DDEV projects and containers (equivalent to ddev stop -a --stop-ssh-agent). Stops Mutagen daemon if running. Usage: ddev poweroff [flags] For full options: ddev help poweroff

Inputs: no named parameters.

ddev_restartB

Restart a DDEV project: stops then starts named project(s). Usage: ddev restart [projectname ...] [flags] Flags: -a/--all, -y/--skip-confirmation For full options: ddev help restart

Inputs: projectPath (required).

ddev_snapshotA

Create, list, restore, or cleanup database snapshots (stored in .ddev/db_snapshots). Restore with action=restore and snapshotName; use ddev snapshot restore --latest for latest. Usage: ddev snapshot [projectname...] [flags] | ddev snapshot restore [name] [flags] Actions: create (optional name), list, restore (snapshotName or --latest), cleanup. Flags: -n/--name, -l/--list, -C/--cleanup, -y/--yes, -a/--all For full options: ddev help snapshot; ddev snapshot restore --help

Inputs: all, yes, name, action, +2 more.

ddev_startA

Start a DDEV project environment. Initializes and configures the web server and database containers. Run from project directory or pass project name(s). Usage: ddev start [projectname ...] [flags] Flags: -a/--all, -y/--skip-confirmation, --skip-hooks For full options: ddev help start

Inputs: projectPath (required), skipHooks, skipConfirmation.

ddev_stopA

Stop and remove the containers of a DDEV project. Non-destructive: leaves database and code intact. Run from project dir or pass project name(s). Usage: ddev stop [projectname ...] [flags] For full options (e.g. --remove-data, --snapshot): ddev help stop

Inputs: projectPath (required).

ddev_versionA

Display the version of the DDEV binary and its components. Usage: ddev version [flags] For full options: ddev help version

Inputs: no named parameters.

message_complete_notificationA

Send a simple OS notification to the user

Inputs: title (required), message (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 14 tools

    Disambiguation4/5

    Most tools target distinct operations (start, stop, restart, snapshot, exec, import/export). The only mild overlap is ddev_describe and ddev_list, both showing project status, but descriptions clarify that describe gives detailed info for a single project while list enumerates projects.

    Naming Consistency3/5

    All tools use lowercase snake_case with a ddev_ prefix, but the second part is inconsistent: some are verb_noun (export_db, import_db), some are bare verbs (start, stop, exec), some are nouns (logs, snapshot, version, help). message_complete_notification breaks the ddev_ pattern entirely, making the naming convention mixed.

    Tool Count5/5

    14 tools is well within the ideal range for a local development environment orchestrator. Each tool covers a distinct DDEV command or workflow, and none feel redundant or excessive for the scope.

    Completeness4/5

    The set covers core DDEV lifecycle (start, stop, restart, poweroff, list, describe), database operations (export/import/snapshot), logs, exec, version, and help. Minor gaps exist (e.g., no direct project deletion or config command), but ddev_exec with shell access can compensate for many missing operations.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI agents to interact with Magento 2 development environments through comprehensive tools for module management, database operations, cache control, configuration management, and system diagnostics. Supports complete development workflows from module creation to deployment and troubleshooting.
      28
      178 npm
      41
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to interact with DDEV local development environments by querying databases, managing project states, and executing container commands. It provides comprehensive control over local services with a security-first approach using whitelisted operations.
      5
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to manage Odoo development environments by providing tools for server control, module management, database operations, and project navigation.
      4
      11 npm
      2
      MIT