README

MCP server for Drupal via Drush. Lets AI agents (Claude Code, Gemini CLI, etc.) interact with any Drupal 10+/11+ site - locally, over SSH, or via Docker - by executing Drush commands.

Two packages:

• @bloomidea/drush-mcp (npm) - TypeScript MCP server
• bloomidea/drush-mcp-bridge (Composer) - PHP Drush bridge for structured entity operations

Requirements

• Node.js 18+
• PHP 8.1+
• Drush 12+ or 13+
• Drupal 10+ or 11+

Quick Start

Install the MCP server:

npm install -g @bloomidea/drush-mcp

Install the Drush bridge on your Drupal site:

composer require bloomidea/drush-mcp-bridge

Add the agent skill so your agent knows how to work with Drupal entities, fields, and groups:

npx skills add Bloomidea/drush-mcp

"create a task in the Atrium group" / "list all published articles" / "check Drupal status" / "add a comment to node 123"

Works with Claude Code, Cursor, Codex, Gemini, Windsurf, and 37+ agents.

Register in Claude Code (local):

claude mcp add drupal -- drush-mcp --local --command "drush"

Or with SSH:

claude mcp add drupal -- drush-mcp --ssh --host example.com --user deploy --root /var/www/html

Configuration

Three methods: CLI flags, YAML config file, or environment variables.

CLI Flags

# Local
drush-mcp --local --command "ddev drush"

# SSH
drush-mcp --ssh --host example.com --user deploy --root /var/www/html

# Docker (static container name)
drush-mcp --docker --host example.com --user deploy --container mycontainer

# Docker (dynamic container lookup via filter)
drush-mcp --docker --host example.com --user deploy --container-filter "label=coolify.serviceName=myapp"

Config File

Create drush-mcp.yml in your project root or home directory, or pass --config path:

sites:
  production:
    transport: ssh
    host: example.com
    user: deploy
    root: /var/www/html
  local:
    transport: local
    command: ddev drush

defaults:
  timeout: 30

Drush Site Aliases

If your project already uses Drush site aliases (drush/sites/self.site.yml), the fields map directly to drush-mcp.yml:

So a Drush alias like:

# drush/sites/self.site.yml
live:
  host: example.com
  user: deploy
  root: /var/www/html
  uri: https://example.com

Becomes:

# drush-mcp.yml
sites:
  live:
    transport: ssh
    host: example.com
    user: deploy
    root: /var/www/html
    uri: https://example.com

The main difference is that drush-mcp requires an explicit transport field and supports additional options like containerFilter for dynamic Docker container lookup.

File upload settings (per-site)

drupal_file_upload and drupal_file_attach accept optional file_upload settings in drush-mcp.yml (all keys optional, defaults shown):

sites:
  production:
    transport: ssh
    host: example.com
    user: deploy
    root: /var/www/html
    uri: https://example.com   # required to get a real public URL back
    file_upload:
      max_size: 10485760                # 10 MB; further capped by upload_max_filesize / post_max_size
      allowed_extensions: [txt, md, pdf, png, jpg, jpeg, gif, svg, log, sql, json, yaml, yml, zip, tar, gz]
      default_uid: 0                    # 0 = anonymous; set to a real user ID for attribution
      destination_prefix: mcp-uploads   # files land in <scheme>://<prefix>/<UTC YYYY-MM>/

Without a uri configured for the site, the tool still works but url in the response is null (drush in CLI mode without --uri cannot build a routable public URL).

Environment Variables

Dynamic Container Resolution

When using Docker-based hosting platforms (Coolify, Docker Swarm, etc.), container names change on every deploy. Use --container-filter or the containerFilter config option with any valid docker ps --filter expression:

# Coolify: match by service name label
drush-mcp --docker --host example.com --user root --container-filter "label=coolify.serviceName=myapp-web"

# Docker Compose: match by compose service
drush-mcp --docker --host example.com --user root --container-filter "label=com.docker.compose.service=web"

# Match by image name
drush-mcp --docker --host example.com --user root --container-filter "ancestor=myimage:latest"

Or in drush-mcp.yml:

sites:
  production:
    transport: docker
    host: example.com
    user: root
    containerFilter: "label=coolify.serviceName=myapp-web"

The container name is resolved fresh on every command via docker ps --filter, so it automatically picks up new containers after deploys.

Coolify Setup

If your Drupal site runs on Coolify:

1. Set a service name in Coolify: Configuration > General > Name (e.g., atrium-web)
2. Use the label filter:

   claude mcp add drupal-production -- drush-mcp \
     --docker --host your-server.com --user root \
     --container-filter "label=coolify.serviceName=atrium-web"

3. Install the bridge on your Drupal site: composer require bloomidea/drush-mcp-bridge
4. Deploy - the bridge commands are available immediately

Tools

All 19 tools are available regardless of transport:

Multi-site

When multiple sites are configured, all tools accept a site parameter to target a specific site. With a single site configured, it is resolved automatically.

Drush Bridge Commands

The bloomidea/drush-mcp-bridge Composer package provides structured entity commands auto-discovered by Drush:

Install via Composer and Drush picks them up automatically - no additional registration needed.

Important: The bridge command class file must be named *DrushCommands.php (not *Commands.php) for Drush 12's PSR-4 discovery. The class also provides a static create() factory method for dependency injection from Drupal's service container.

How is this different from the Drupal MCP Server module?

The MCP Server Drupal module takes a different approach: it runs the MCP server inside Drupal as a PHP module, exposing tools via HTTP with OAuth 2.1 authentication.

drush-mcp runs outside Drupal as a standalone TypeScript process that executes Drush commands over shell, SSH, or Docker. This leads to several practical differences:

When to use drush-mcp: You already have SSH/shell access to your sites, want to connect multiple Drupal sites through one MCP server, or prefer not to install additional Drupal modules. Good for development workflows with DDEV/Lando and for ops teams managing multiple sites.

When to use MCP Server module: You need fine-grained OAuth-based access control, want to expose custom Tool API plugins, or prefer keeping everything within Drupal's ecosystem.

Security

There are no artificial capability tiers. If you have Drush access to a site, you have access to all tools.

The security boundary is transport access: SSH keys, Docker socket permissions, or local process access. Bridge commands (mcp:entity-*) enforce Drupal's entity access checks. Power tools (drupal_drush, drupal_php_eval, drupal_sql_query) do not - treat them accordingly.

License

MIT