MCP server for Drupal via Drush

Lets AI agents (Claude Code, Gemini CLI, Cursor, Codex, Windsurf, and others) interact with any Drupal 10+/11+ site, locally, over SSH, or via Docker, by executing Drush commands through the Model Context Protocol (MCP).

Two packages work together:

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

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

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

Features

  • 19 MCP tools: entity CRUD, file upload and field attach (with file.usage tracking and rollback), introspection with allowed values, configuration, cache, watchdog, user management, arbitrary Drush/PHP/SQL
  • 3 transport methods: local shell (DDEV, Lando, plain Drush), SSH, Docker
  • Dynamic container resolution for platforms like Coolify and Docker Swarm
  • Multi-site support: one MCP server, multiple Drupal sites
  • Entity introspection returns field types, required status, cardinality, taxonomy term allowed values, and list field options
  • Single-call file upload + attach to file or image fields on nodes, comments, and other entities, with extension/size validation against the field's own settings and automatic rollback on save failure
  • AI agent skill file with workflows, field formats, Group module patterns, and safety rules
  • Works without installing any Drupal module. Built-in Drush commands work out of the box. The bridge package adds structured entity operations.

Tools

Tool Description
drupal_entity_create Create entity from JSON fields
drupal_entity_read Load entity by type + ID
drupal_entity_update Update fields on existing entity
drupal_entity_list Query entities with filters
drupal_entity_delete Delete entity by type + ID
drupal_introspect Discover entity types, bundles, fields
drupal_cache_rebuild Clear all caches
drupal_watchdog View recent log entries
drupal_status Site info (version, DB, PHP)
drupal_config_get Read configuration value
drupal_config_set Write configuration value
drupal_field_info Field definitions for entity type
drupal_user_create Create user account
drupal_user_block Block user account
drupal_file_upload Upload bytes and create a managed file entity
drupal_file_attach Upload bytes and attach to a file/image field on a node, comment, or other entity in one round trip
drupal_drush Run any Drush command
drupal_php_eval Execute PHP code
drupal_sql_query Run SQL query

How is this different from the MCP Server module?

The MCP Server Drupal module 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.

drush-mcp MCP Server module
Install on Drupal Optional Composer package (bridge) Required module + Tool API + Simple OAuth
Runs as External Node.js process Inside Drupal's PHP runtime
Transport STDIO (local shell, SSH, Docker) HTTP endpoint (/_mcp)
Auth model SSH keys / shell access OAuth 2.1 tokens
Config YAML file or CLI flags Drupal config entities
Tools 19 fixed tools + arbitrary Drush Extensible via Tool API plugins
Multi-site Built-in (one server, many sites) One instance per Drupal site
Works without Drupal changes Yes (built-in Drush commands work without the bridge) No (module must be installed and configured)

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.

Requirements

  • PHP 8.1+
  • Drush 12+ or 13+
  • Drupal 10+ or 11+
  • Node.js 18+ (for the MCP server)

Full documentation, configuration options, and Coolify setup at github.com/Bloomidea/drush-mcp

Supporting organizations: 

Project information

  • Ecosystem: Drush
  • Created by introfini on , updated
  • shieldStable releases for this project are covered by the security advisory policy.
    There are currently no supported stable releases.

Releases