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 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 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 [email protected]: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:deleteare 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:
- Fork and Clone: Standard GitHub workflow
- Install Dependencies:
npm install - Build:
npm run build - Make 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! 🚀
