PHPackages bloomidea/drush-mcp-bridge - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. bloomidea/drush-mcp-bridge ActiveDrupal-drush[Utility & Helpers](/categories/utility) bloomidea/drush-mcp-bridge ========================== Drush commands for AI agent entity operations and schema introspection v0.2.1(1mo ago)35↓100%1MITTypeScriptPHP >=8.1CI passing Since Mar 14Pushed 1mo ago1 watchersCompare [ Source](https://github.com/Bloomidea/drush-mcp)[ Packagist](https://packagist.org/packages/bloomidea/drush-mcp-bridge)[ RSS](/packages/bloomidea-drush-mcp-bridge/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (3)Dependencies (1)Versions (4)Used By (0) drush-mcp ========= [](#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 ------------ [](#requirements) - Node.js 18+ - PHP 8.1+ - Drush 12+ or 13+ - Drupal 10+ or 11+ Quick Start ----------- [](#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](skills/drupal/SKILL.md) 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](https://add-skill.org/). 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 ------------- [](#configuration) Three methods: CLI flags, YAML config file, or environment variables. ### CLI Flags [](#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 [](#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 [](#drush-site-aliases) If your project already uses [Drush site aliases](https://www.drush.org/13.x/site-aliases/) (`drush/sites/self.site.yml`), the fields map directly to `drush-mcp.yml`: Drush alias fielddrush-mcp equivalent`host``host``user``user``root``root``uri``uri``docker.service``container`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. ### Environment Variables [](#environment-variables) VariableDescription`DRUSH_MCP_TRANSPORT``local`, `ssh`, or `docker``DRUSH_MCP_HOST`SSH/Docker host`DRUSH_MCP_USER`SSH/Docker user`DRUSH_MCP_ROOT`Drupal root path`DRUSH_MCP_COMMAND`Local command (e.g. `ddev drush`)`DRUSH_MCP_CONTAINER`Docker container name`DRUSH_MCP_CONTAINER_FILTER`Docker filter for dynamic container lookupDynamic Container Resolution ---------------------------- [](#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 [](#coolify-setup) If your Drupal site runs on [Coolify](https://coolify.io/): 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 ----- [](#tools) All 17 tools are available regardless of transport: ToolDescription`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_drush`Run any Drush command`drupal_php_eval`Execute PHP code`drupal_sql_query`Run SQL queryMulti-site ---------- [](#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 --------------------- [](#drush-bridge-commands) The `bloomidea/drush-mcp-bridge` Composer package provides structured entity commands auto-discovered by Drush: CommandDescription`mcp:entity-create`Create an entity`mcp:entity-read`Read an entity`mcp:entity-update`Update an entity`mcp:entity-list`Query entities`mcp:introspect`Introspect entity types and fieldsInstall 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? -------------------------------------------------------- [](#how-is-this-different-from-the-drupal-mcp-server-module) The [MCP Server](https://www.drupal.org/project/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: drush-mcpMCP Server module**Install on Drupal**Optional Composer package (bridge)Required module + Tool API + Simple OAuth**Runs as**External Node.js processInside Drupal's PHP runtime**Transport**STDIO (local shell, SSH, Docker)HTTP endpoint (`/_mcp`)**Auth model**SSH keys / shell accessOAuth 2.1 tokens**Config**YAML file or CLI flagsDrupal config entities**Tools**17 fixed tools + arbitrary DrushExtensible 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. Security -------- [](#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 ------- [](#license) MIT ### Health Score 37 — LowBetter than 83% of packages Maintenance89 Actively maintained with recent releases Popularity10 Limited adoption so far Community8 Small or concentrated contributor base Maturity34 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 3 Last Release 57d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/aba63db544db2ee4535151d72c8997fddeed8213ec9aaa5b93ca4af4b9be8f1c?d=identicon)[introfini](/maintainers/introfini) --- Top Contributors [![introfini](https://avatars.githubusercontent.com/u/104880?v=4)](https://github.com/introfini "introfini (19 commits)") --- Tags ai-agentsclaude-codedrupaldrushmcpmcp-server ### Embed Badge ![Health badge](/badges/bloomidea-drush-mcp-bridge/health.svg) ``` [![Health](https://phpackages.com/badges/bloomidea-drush-mcp-bridge/health.svg)](https://phpackages.com/packages/bloomidea-drush-mcp-bridge) ``` ### Alternatives [farmos/farmos A web-based farm record keeping application. 1.2k6.7k1](/packages/farmos-farmos)[lullabot/drainpipe An automated build tool to allow projects to have a set standardized operations scripts. 41716.4k2](/packages/lullabot-drainpipe)[acquia/cohesion Site Studio 271.6M7](/packages/acquia-cohesion)[ec-europa/toolkit Toolkit packaged for Drupal projects based on Robo. 38244.6k16](/packages/ec-europa-toolkit)[eiriksm/site-schema Allows you to get the complete picture of a site schema, to use for CI for example 111.4M](/packages/eiriksm-site-schema)[acquia/drupal-recommended-settings The composer plugin for adding drupal-recommended-settings for Acquia Cloud. 101.1M4](/packages/acquia-drupal-recommended-settings) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)