DDEV MCP
Supports CakePHP project environments within DDEV, enabling DDEV management commands.
Allows running Composer commands like install and update via ddev_exec.
Enables executing Cypress tests inside DDEV containers.
Provides Drush command execution for cache clearing, configuration export, and more.
Supports Artisan commands for migrations and other Laravel tasks.
Allows direct MySQL queries and database operations within DDEV projects.
Integrates with Platform.sh for environment management, with dangerous command protection.
Enables Redis commands like cache flushing and memory inspection.
Supports Symfony console commands for cache clearing and more.
Supports TYPO3 development environments with DDEV management.
Provides WP-CLI commands for plugin management, core updates, and cache flushing.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@DDEV MCP clear Drupal cache"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 helpoutput. 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_exectool handles all CMS/framework commandsDrupal: 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 --versionNode.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 devConfiguration
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:deleteare blocked by defaultDatabase 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 buildand 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 pointContributing
This project is designed for team collaboration with familiar JavaScript/TypeScript patterns:
Fork and Clone: Standard GitHub workflow
Install Dependencies:
npm installBuild:
npm run buildMake Changes: Follow existing patterns
Test: Manually (Use it in your ddev project)
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! 🚀
Available Tools
14 toolsddev_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:
"curl http://solr:8983/solr/admin/cores?action=STATUS" - Check cores
"curl http://solr:8983/solr/corename/select?q=:" - Query 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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
Plan Salesforce deploys, open pull requests and trigger pipelines from your AI client.
Deploy and manage Jade Hosting projects from AI clients. Jade account and OAuth required.
Deploy and run apps, databases, domains, storage, email and search on Dbrij from your AI assistant.
Deploy and manage your apps, databases, storage, and scheduled jobs from your AI agent
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables 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.28178 npm41MIT
- AlicenseCqualityDmaintenanceEnables AI-assisted development for Webasyst framework projects, including creating and managing apps, plugins, themes, and configurations through natural language commands.387 npm8MIT
- AlicenseAqualityDmaintenanceEnables 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.53MIT
- AlicenseAqualityCmaintenanceEnables AI assistants to manage Odoo development environments by providing tools for server control, module management, database operations, and project navigation.411 npm2MIT