drush-mcp

MCP server for Drupal via Drush. Connects to any Drupal 10+/11+ site over local shell, SSH, or Docker.

Rules of Engagement

• Introspect before creating: Always call drupal_introspect with entity_type and bundle before creating or updating entities. This returns required fields, field types, allowed values for taxonomy references, and list field options. Never guess field values.
• Use the user parameter: Bridge tools (drupal_entity_create, drupal_entity_read, drupal_entity_update, drupal_entity_list, drupal_introspect, and uid on the file tools) act as one Drupal account and apply its access checks: entity create, view and update access, field view access on what comes back, and edit access on every field whose value changes. Pass user to act as a given account. Without it the site's run_as applies, and without that, anonymous; before 0.6.0 the fallback was uid 1, so a call that used to work without user may now answer access_denied. Pass the account whose permissions the work should have, not uid 1.
• Read refusals as answers, not glitches: access_denied means Drupal refused the acting account (the message carries Drupal's reason). user_not_allowed means the site runs on the read-only or content tools profile and pins the account to its run_as; tool_disabled means the site switched that tool off; param_not_allowed means a restricted site does not let the agent choose a file's scheme or destination (drop them, the field decides); bridge_too_old means the site's bridge must be upgraded before a restricted profile can run. Report these to the user; do not retry as another account or route around them with drupal_php_eval.
• Confirm before destructive operations: drupal_entity_delete, drupal_config_set, drupal_php_eval, and drupal_sql_query modify data. Always confirm with the user before executing.
• Multi-site: When multiple Drupal sites are configured, every tool accepts a site parameter. With a single site, it resolves automatically.
• Drush site aliases: If the project has a drush/sites/self.site.yml file, its entries (host, user, root, uri) map directly to drush-mcp.yml site config. Useful for discovering connection details when setting up new sites.

Tools

A site may expose fewer tools than listed here. Its tools profile decides: read-only keeps entity read and list, introspect, field info and status; content adds entity create and update and file attach; full (the default) has all of them. A tool missing from the tool list is switched off on purpose.

Entity Operations (bridge commands)

These use the drush-bridge package (bloomidea/drush-mcp-bridge) installed on the Drupal site.

System Operations (built-in Drush)

User Operations (built-in Drush)

Power Tools (built-in Drush)

Field Value Formats

Entity references (taxonomy terms, users, nodes)

{"field_name": {"target_id": 42}}

Multiple values (if cardinality > 1):

{"field_name": [{"target_id": 42}, {"target_id": 43}]}

Text fields (body, text_with_summary, text_long)

{"body": {"value": "The content here.", "format": "basic_html"}}

Common text formats: basic_html, full_html, plain_text, restricted_html. When unsure, use basic_html.

Simple fields (string, integer, boolean, email)

{"title": "My Title", "status": 1, "field_email": "user@example.com"}

Date fields

{"field_date": "2026-03-15"}
{"field_date": {"value": "2026-03-15T09:00:00", "end_value": "2026-03-15T17:00:00"}}

List fields (select lists)

Use the machine value, not the label. Call drupal_introspect to see allowed_values:

{"field_color": "red"}

Common Workflows

Create an entity (node, comment, etc.)

1. Introspect to discover required fields and allowed values:

   drupal_introspect(entity_type="node", bundle="article")

2. Create with all required fields:

   drupal_entity_create(entity_type="node", bundle="article", fields={"title": "My Article", "body": {"value": "Content", "format": "basic_html"}, "uid": 1})

Add a comment to a node

1. Introspect the comment bundle:

   drupal_introspect(entity_type="comment", bundle="comment_node_article")

   The bundle name is typically comment_node_<content_type>.
2. Create the comment with the correct entity_id, entity_type, field_name, and user:

   drupal_entity_create(
     entity_type="comment",
     bundle="comment_node_article",
     user=4,
     fields={
       "entity_id": {"target_id": 123},
       "entity_type": "node",
       "field_name": "comment_node_article",
       "uid": 4,
       "subject": "My comment",
       "comment_body": {"value": "Comment text.", "format": "basic_html"}
     }
   )

   The user parameter is critical for comments since access checks verify the acting user can reference the target node and use the text format.

Query entities with filters

drupal_entity_list(
  entity_type="node",
  bundle="ol_todo",
  filters={"status": 1},
  limit=10,
  sort="changed:DESC"
)

Read a specific entity

drupal_entity_read(entity_type="node", id=12345)

Update specific fields

drupal_entity_update(entity_type="node", id=12345, fields={"title": "New Title", "field_status": {"target_id": 2}})

Attach a file to a node, comment, or other entity

Use drupal_file_attach to upload bytes and attach to a file or image field in one call. The tool registers file.usage against the host entity, so cascade-deletes work, and rolls back on save failure to avoid orphan files.

Choose the right input mode — content_path vs content_base64:

• content_path (recommended for local agents) — pass an absolute path on the machine running the MCP server. The MCP reads the file from disk and pipes it to Drush. Use this whenever you have the file on the agent's local filesystem. Required for files over ~10–15 KB if the agent talks to the MCP through an LLM provider, because dense base64 inside tool arguments can trigger provider-side safety filters and the call gets rejected. content_path keeps the LLM message stream clean (just a short path string). Since 0.5.1 the path must resolve, symlinks followed, inside the site's content_roots (by default only the system temp directory and /tmp), and the file on disk must itself have an allowed extension. On PATH_OUTSIDE_ROOTS, copy the file into /tmp and upload that copy; do not ask for the root to be widened just to finish the task.
• content_base64 — base64-encoded file bytes. Use when the file is not on the agent's local filesystem (cross-host MCP deployments, content generated in-memory, etc.). Slower for large files because the bytes traverse the LLM message stream.

Exactly one of the two must be provided. Sending both → VALIDATION_ERROR. Sending neither → VALIDATION_ERROR.

Decide between _upload and _attach:

• drupal_file_attach — you know the target (entity + field) and want it bound in one round trip. Field-level extension and size limits are validated before bytes are written.
• drupal_file_upload — you only need a managed file entity (e.g. to reference from a custom workflow). Returns fid for later use. The agent is then responsible for either attaching it (which registers usage) or deleting it.

Required field discovery:

Most file/image fields share the same shape. Common Atrium-style fields:

• node:ol_todo → field_shared_files (multi, type file)
• comment:comment_node_ol_todo → field_shared_files (multi, type file)
• node:article → field_image (single, type image)

When unsure, call drupal_introspect on the bundle and look for fields with "type":"file" or "type":"image".

Attach a PRD/document to an existing task (node) — canonical local agent flow:

drupal_file_attach(
  filename="PRD-feature.md",
  content_path="/Users/me/Dev/myproject/PRD-feature.md",
  entity_type="node",
  entity_id=403055,
  field_name="field_shared_files",
  uid=4
)

Attach to a comment (the more common Atrium pattern):

1. Create the comment first (see "Add a comment to a node" workflow above), capture the returned comment id.
2. Attach the file to the comment:

drupal_file_attach(
  filename="screenshot.png",
  content_path="/tmp/screenshot.png",
  entity_type="comment",
  entity_id=190282,
  field_name="field_shared_files",
  uid=4
)

Image fields with alt/title:

drupal_file_attach(
  filename="hero.jpg",
  content_path="/Users/me/Pictures/hero.jpg",
  entity_type="node", entity_id=12345,
  field_name="field_image",
  alt="Sunset over the harbour", title="Hero image",
  uid=4
)

Cross-host fallback (when the file is not on the agent's local filesystem):

drupal_file_attach(
  filename="generated.md",
  content_base64="<base64 of bytes generated in-memory>",
  entity_type="node",
  entity_id=403055,
  field_name="field_shared_files",
  uid=4
)

Replace existing files instead of appending:

Default mode is append (adds to the existing list, respecting cardinality). Pass mode="replace" to overwrite. On a cardinality=1 field, append into a populated field returns CARDINALITY_EXCEEDED — use replace instead.

Defaults that matter:

• scheme follows the site. drupal_file_attach uses the target field's uri_scheme (what the Drupal upload widget would do) and drupal_file_upload uses the site's system.file default_scheme. Only pass scheme when you need to override that, e.g. private for a sensitive file on a site whose default is public. Before 0.4.0 both tools defaulted to public regardless of the field; if you see uploads landing in public:// on a private-files site, the bridge is older than 0.4.0.
• destination defaults to mcp-uploads/<UTC YYYY-MM>/ so AI uploads stay separate from editorial ones.
• uid defaults to the site's default_uid (anonymous unless configured). For Atrium and similar group-aware sites, pass an explicit uid because anonymous users typically can't post comments or save entities with restricted text formats.

Errors to expect:

URL in response: url is null for private/temporary schemes, and also null when the site has no uri configured in drush-mcp.yml (because drush running in CLI without --uri can't build a real public URL). The uri field (e.g. public://mcp-uploads/2026-05/foo.md) is always populated and is what you should pass back to other Drupal calls.

Working with Groups (Group module v3)

Groups use group and group_relationship entities. Content is linked to groups through relationship entities, not directly. When in doubt about which group to use, ask the user for the group name rather than guessing.

List groups:

drupal_entity_list(entity_type="group", bundle="client", limit=10)

Create a group:

drupal_entity_create(entity_type="group", bundle="bloom", user=4, fields={"label": "My Project", "uid": 4})

Note: groups use label (not title) for the name field.

Add a member to a group:

drupal_entity_create(
  entity_type="group_relationship",
  bundle="bloom-group_membership",
  user=4,
  fields={
    "gid": {"target_id": GROUP_ID},
    "entity_id": {"target_id": USER_ID},
    "plugin_id": "group_membership",
    "group_type": {"target_id": "bloom"},
    "uid": 4
  }
)

Add content (e.g. a task) to a group:

drupal_entity_create(
  entity_type="group_relationship",
  bundle="bloom-group_node-ol_todo",
  user=4,
  fields={
    "gid": {"target_id": GROUP_ID},
    "entity_id": {"target_id": NODE_ID},
    "plugin_id": "group_node:ol_todo",
    "group_type": {"target_id": "bloom"},
    "uid": 4
  }
)

Discover available relationship types for a group type:

drupal_introspect(entity_type="group_relationship")

This lists all relationship bundles (e.g., bloom-group_membership, bloom-group_node-ol_todo, client-group_node-ol_todo). Use this to find the correct bundle before adding content to a group.

Key details:

• Relationship bundle format: {group_type}-{plugin_id_with_hyphens} (e.g., bloom-group_node-ol_todo)
• The plugin_id field value uses colons: group_node:ol_todo, group_membership
• To find the right bundle: the bundle name replaces colons with hyphens and prepends the group type. So for group type bloom and content plugin group_node:ol_todo, the bundle is bloom-group_node-ol_todo
• To list content in a group, query group_relationship filtered by gid:

  drupal_entity_list(entity_type="group_relationship", bundle="bloom-group_node-ol_todo", filters={"gid": GROUP_ID})

• To list group members: filter by the *-group_membership bundle
• When deleting: remove group_relationship entities first, then the content, then the group

Check site health

drupal_status()
drupal_watchdog(count=10, severity="error")
drupal_cache_rebuild()

Read and write configuration

drupal_config_get(name="system.site")
drupal_config_get(name="system.site", key="name")
drupal_config_set(name="system.site", key="name", value="My Site")

Run arbitrary Drush commands

drupal_drush(command="pm:security")
drupal_drush(command="queue:list")
drupal_drush(command="state:get", arguments=["system.cron_last"])
drupal_drush(command="core:status", format="json")

Use format="json" to get structured output from built-in Drush commands. Common formats: json, table, yaml.

Execute PHP or SQL

drupal_php_eval(code="echo \\Drupal::VERSION;")
drupal_sql_query(query="SELECT COUNT(*) FROM node_field_data WHERE status = 1")

Drush Commands Reference

Commands available via drupal_drush(command="...", arguments=[...], format="json"). This covers commands beyond the dedicated MCP tools.

Cron & Maintenance

Modules & Themes

Config Management

State API

State is for environment-specific values (last cron run, maintenance mode). Config is for site configuration that syncs between environments.

Database

Users (beyond create/block)

Note: user:login generates URLs based on the site's uri setting. If links show http://default, the site needs a uri configured in drush-mcp.yml.

Roles & Permissions

Queues

Migrations

Views

Locale & Translations

Deploy

Image

Routing

Introspect Modes

drupal_introspect operates in three modes depending on which parameters you provide:

Always use the third mode (type + bundle) before creating entities to discover required fields and valid values.

Entity Types Cheat Sheet

Common Drupal entity types:

Safety Rules

Write operations (drupal_entity_create, drupal_entity_update, drupal_entity_delete, drupal_config_set) modify data. Always confirm with the user before executing.

Power tools (drupal_drush, drupal_php_eval, drupal_sql_query) provide unrestricted access to the Drupal runtime and database. These can break a site. Use with caution and always confirm.

drupal_php_eval executes arbitrary PHP. Double-check the code before running. Syntax errors or fatal errors can produce unhelpful output.

Error Handling

All errors are returned as structured JSON:

{"error": "drush_error", "message": "Entity \"node\" with ID \"99999\" not found."}

{"error": "validation_error", "message": "Entity validation failed.", "violations": [{"field": "title", "message": "This value should not be null."}]}

When you get a validation_error, check the violations array for which fields failed and why. Often it means a required field is missing or an entity reference target doesn't exist.