home / mcp / ddev mcp server

DDEV MCP Server

Provides a protocol-enabled interface to query DDEV databases, manage projects, and execute development commands with a whitelist-based security model.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "akibaat-ddev-mcp": {
      "command": "ddev-mcp",
      "args": []
    }
  }
}

You can run the DDEV MCP Server to let LLMs and AI assistants interact with your local DDEV environments. It provides safe, read-only access to your database and development workflow, while offering controlled write capabilities when you explicitly enable them. Use it to query databases, inspect project status, manage DDEV projects, run development commands, and analyze your DDEV configuration through a consistent MCP interface.

How to use

Use a client that supports MCP to connect to the DDEV MCP Server. You will typically configure a local MCP server entry that points at a local command runner and then issue requests to perform actions such as querying databases, listing project status, starting or stopping projects, running commands in containers, or inspecting logs.

How to install

Prerequisites you need before installing are straightforward. You should have Node.js 20+ installed, and DDEV must be installed and available on your system PATH. Your DDEV projects should already be configured.

Step-by-step installation flow you can follow:

# Install from a released package (recommended)
# Download the .tgz package from the latest release and install globally
npm install -g ./ddev-mcp-0.8.0.tgz

# Verify installation
ddev-mcp --help
```

```bash
# Alternative: Build from source (if you prefer)
# Clone the repository and build locally
git clone https://github.com/AkibaAT/ddev-mcp.git
cd ddev-mcp
npm install
npm run build
npm install -g .
```

```bash
# Quick installation script (if available in your setup)
git clone https://github.com/AkibaAT/ddev-mcp.git
cd ddev-mcp
chmod +x install.sh
./install.sh

Configuration and security notes

The MCP server operates with a whitelist-based security model by default. This means only explicitly allowed read-only operations are permitted unless you enable write operations with a specific flag. Catastrophic operations such as dropping databases or shutting down services are never allowed, even when write mode is enabled.

Key security rules you should know: - Read-only actions are allowed only if explicitly whitelisted. - Write operations require the --allow-write flag. - Catastrophic operations (DROP DATABASE, SHUTDOWN) and file-system access are blocked by default.

To enable write operations when you trust the client, start the MCP server with the write-enabled flag:

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

# Enable write operations with single project mode for a dedicated project
`ddev-mcp --allow-write --single-project my-project

MCP client configuration (examples)

Configure your MCP client to connect to these local servers. The following entries show two valid stdio configurations based on the supported commands. Use them as a starting point and adjust for your environment.

{
  "mcpServers": {
    "ddev": {
      "command": "ddev-mcp",
      "args": []
    },
    "ddev-write": {
      "command": "ddev-mcp",
      "args": ["--allow-write", "--single-project", "development-site"]
    }
  }
}

Project context and current status

When using single project mode, you gain rich contextual information about the current project through a special resource that represents the active DDEV project in use. This helps the LLM understand the project context, including its name, status, database type, and access URL.

Usage examples and workflows

Typical workflows you can perform include: - Database development: run queries against your local DDEV databases and inspect schemas. - Debugging: retrieve and analyze service logs from DDEV. - Project management: start, stop, or restart DDEV projects and verify readiness. - Schema analysis: examine relationships between tables in your current project database. - Development workflow: apply migrations and verify updated schemas by running commands and inspecting results.

Testing and debugging

You can verify the MCP server is installed and accessible by checking the global binary and testing DDEV integration. For example, confirm the MCP binary is on your PATH and run a DDEV-related query or action to ensure the server responds as expected.

Requirements

- Node.js 20+ - DDEV installed and accessible via PATH - DDEV projects configured and ready to use

Development and testing commands

Development workflow you can follow while building or contributing to the MCP server includes starting a development server with ts-node, building the TypeScript project, and running tests. You will use common npm scripts such as dev, build, start, and tests.

npm run dev
npm run build
npm run start

npm run lint
npm run lint:fix
npm run lint:check

npm run test
npm run test:watch
npm run test:ci

Available tools

ddev_db_query

Execute SQL queries with support for PostgreSQL, MySQL, and MariaDB, with detailed error reporting.

ddev_start_project

Start a DDEV project to bring it into a running state.

ddev_stop_project

Stop a running DDEV project.

ddev_restart_project

Restart a DDEV project.

ddev_logs

Retrieve service logs for debugging and analysis.

ddev_exec_command

Execute commands inside the DDEV web service.

ddev_ssh

Obtain SSH access and connection information to DDEV services.

ddev_list_projects

List all DDEV projects with their current status.

ddev_project_status

Get the current status and configuration of a DDEV project.

ddev_composer_command

Run Composer commands inside the DDEV environment.

ddev_xdebug

Control Xdebug state (on/off/toggle/status) for debugging.

ddev_share

Share your project via ngrok for external access.

ddev_mailpit

Access Mailpit for email testing in development.

ddev_export_db

Export database dumps for backup or transfer.

ddev_import_db

Import database dumps into the DDEV project.