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:
- @bloomidea/drush-mcp (npm) - TypeScript MCP server that orchestrates Drush commands over local shell, SSH, or
Docker - bloomidea/drush-mcp-bridge (Composer) - Drush commands for entity CRUD, schema introspection, and file upload
Quick start
Install the MCP server:
npm install -g @bloomidea/drush-mcpInstall the Drush bridge on your Drupal site:
composer require bloomidea/drush-mcp-bridgeAdd the agent skill so your agent knows how to work with Drupal entities, fields, and groups:
npx skills add Bloomidea/drush-mcpRegister 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/htmlWorks with Claude Code, Cursor, Codex, Gemini, Windsurf, and 37+ agents.
Features
- 19 MCP tools: entity CRUD, file upload and field attach (with
file.usagetracking 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
fileorimagefields 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
Project information
- Ecosystem: Drush
- Created by introfini on , updated
Stable releases for this project are covered by the security advisory policy.
There are currently no supported stable releases.
