drush-mcp

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. The file is used when no transport or host flag is given on the command line; a site defined by CLI flags takes precedence over it (only the file's defaults: block is still read). Per-site settings such as file_upload therefore need the file route: point the MCP server entry at drush-mcp with no site flags and describe the sites in the YAML.

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

Uploads land in the scheme the site expects: drupal_file_attach uses the target field's uri_scheme and drupal_file_upload uses system.file default_scheme. Pass scheme only to override.

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>/
      content_roots: [<system temp dir>, /tmp]   # where content_path may read from

content_roots lists the local directories content_path may read from, on
the machine running the MCP server. A path is accepted only when it sits inside
one of them both as written and once symlinks and .. are resolved, and the
file it resolves to must itself carry an allowed extension: naming a key
key.txt in filename no longer gets ~/.ssh/id_rsa through. A root that is
a symlink (/tmp on macOS) matches under either spelling. Entries are absolute
or start with ~/; a root that does not exist is skipped. The default is the system temp
directory and /tmp, so the usual flow (write or resize the file into /tmp,
then upload it) keeps working. Add a project or documents folder when agents
should upload from there, set [] to turn content_path off, or set [/] to
get the 0.5.0 behaviour of reading any path back.

The same block is accepted under defaults, applying to every site that does
not set its own. That is the only route into a server started from CLI flags:
when flags define the site, the config file's sites are discarded and only
its defaults survive, so a flag-configured server has no file_upload of its
own and no way to grow one.

defaults:
  timeout: 30
  file_upload:
    allowed_extensions: [txt, md, pdf, png, jpg, jpeg, gif, svg, html, htm, log, sql, json, yaml, yml, zip, tar, gz]
    content_roots: [/tmp, ~/Dev, ~/Downloads]

Resolution is three layers deep, each overriding the one before it key by key:
the built-in defaults, then defaults.file_upload, then the site's own block.
allowed_extensions and content_roots replace the list rather than
extending it, at every layer: a content_roots that should still include
/tmp has to name it.

Before adding html, htm or anything else a browser executes, know what the
list is and is not. It gates the agent, not a person: drupal_file_attach
already intersects with the target field's own file_extensions, and anyone
with an account can upload against that same field allowlist through the site's
own forms. What the list buys is that an agent talked into it by a poisoned
comment cannot write active content, which matters until the site serves
uploads with something like Content-Security-Policy: sandbox allow-scripts.
Note that svg ships in the built-in list and is the same class of document as
html.

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