ddev-playwright-mcp

A DDEV add-on that provides a Playwright MCP server for headless browser automation via the Model Context Protocol. It gives AI agents a real Chromium browser to interact with your Drupal site: navigate pages, fill forms, take screenshots, and verify UI state programmatically.

Part of DDEV AI Workspace — a modular ecosystem of DDEV add-ons for AI-powered Drupal development. Install the full stack with one command: ddev add-on get trebormc/ddev-ai-workspace

Created by Robert Menetray · Sponsored by DruScan

Note: This add-on is typically installed automatically as a dependency of ddev-opencode, ddev-claude-code, or ddev-ralph. You rarely need to install it directly.

Quick Start

The recommended way to install this add-on is through the DDEV AI Workspace, which installs all tools and dependencies with a single command:

ddev add-on get trebormc/ddev-ai-workspace
ddev restart

This add-on is also automatically installed as a dependency when you install ddev-opencode, ddev-claude-code, or ddev-ralph. You rarely need to install it directly.

Standalone installation

If you need to install it individually (requires familiarity with the DDEV add-on ecosystem):

ddev add-on get trebormc/ddev-playwright-mcp
ddev restart

What It Does

This add-on runs a Playwright MCP server as a DDEV service with headless Chromium. It exposes an MCP endpoint at http://playwright-mcp:8931/mcp accessible from other containers in the DDEV network.

Use cases:

• AI-driven development: Let AI agents (OpenCode, Claude Code) interact with your site through a real browser
• Visual testing: Take screenshots and verify UI state programmatically
• Browser automation: Automate form submissions, navigation, and interactions

Usage

From Other Containers

Connect to the MCP server at:

http://playwright-mcp:8931/mcp

Screenshots

Screenshots are saved to the screenshots/ directory in your project root, accessible from both the container and the host. The add-on creates that directory at install time as your user, and the container runs with your UID, so everything in it stays yours.

Upgrading from a release before v1.0.60? Earlier versions let Docker create ./screenshots on first start, which made it root:root on Linux and blocked moving or deleting the project directory later. Fix an existing project once with sudo chown -R "$(id -un):$(id -gn)" screenshots from the project root.

Custom Image Version

To use a specific Playwright MCP image version:

ddev dotenv set .ddev/.env.playwright-mcp --playwright-mcp-image=mcr.microsoft.com/playwright/mcp:v1.2.0
ddev restart

Configuration

Tips

• Use HTTP (not HTTPS) when navigating to your DDEV site from Playwright to avoid SSL certificate issues in local environments.
• The MCP server runs in shared browser context mode. Cookies and sessions persist across requests.
• Screenshots output directory: /var/www/html/screenshots (mapped to ./screenshots/ on host).

Uninstallation

ddev add-on remove ddev-playwright-mcp
ddev restart

Part of DDEV AI Workspace

This add-on is part of DDEV AI Workspace, a modular ecosystem of DDEV add-ons for AI-powered Drupal development.

Disclaimer

This project is an independent initiative by Robert Menetray, sponsored by DruScan. It is not affiliated with Anthropic, OpenCode, Beads, Playwright, Microsoft, or DDEV. AI-generated code may contain errors. Always review changes before deploying to production.

License

Apache-2.0. See LICENSE.