Labsco
AkibaAT logo

DDEV MCP Server

★ 3

from AkibaAT

Manage DDEV projects, enabling LLM applications to interact with local development environments through the MCP protocol.

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#email#automation#e-commerce#database#devops#git#maps#security

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:

# Enable write operations
ddev-mcp --allow-write

# Enable write operations with single project mode
ddev-mcp --allow-write --single-project my-project

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

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:

{
  "project": {
    "name": "project-id",
    "status": "running", 
    "dbType": "postgres",
    "url": "https://project-id.ddev.site",
    "description": "DDEV project 'project-id' (running) using postgres database"
  },
  "serverConfig": {
    "securityMode": "read-only",
    "allowWriteOperations": false
  }
}

Testing & Debugging

Test with MCP Inspector

# Global installation
npx @modelcontextprotocol/inspector ddev-mcp

# Local installation
npx @modelcontextprotocol/inspector node dist/index.js

# Development mode
npx @modelcontextprotocol/inspector node --loader ts-node/esm index.ts

Verify Installation

# Check if globally installed
which ddev-mcp

# Test DDEV integration
ddev list --json-output

Development

Building and Running

npm run dev         # Run with ts-node
npm run build       # Build TypeScript
npm run start       # Run built version

Code Quality

npm run lint        # Run ESLint
npm run lint:fix    # Fix auto-fixable ESLint issues
npm run lint:check  # Run ESLint with strict checking (CI)

Testing

npm run test        # Run tests
npm run test:watch  # Run tests in watch mode
npm run test:ci     # Run tests for CI (with coverage)