Skip to content

Tools Reference

Selected tools from the 414-tool catalog, documented with their parameters, return values, and errors. The All Tools page lists every tool with its description, use case, example call, and live-test status; the complete list also lives in the README's Tools section.

Content Management

create_node

Create a single node of the specified bundle with given fields.

Parameters:

Name Type Required Description
bundle string Yes Content type bundle (e.g., 'article', 'page')
fields dict Yes Field values. Must include 'title'

Returns: Created node data with id, type, and attributes

Errors: - ValidationError — If 'title' is missing - ClientError — If the API request fails


query_nodes

Query nodes with filters, sorts, includes, and pagination.

Parameters:

Name Type Required Default Description
bundle string No — Filter by content type
filters dict No — Field filters
sorts list[string] No — Sort order
include string No "" Relationship includes
page_limit integer No 50 Items per page (1-500)
page_offset integer No 0 Offset from start

Returns: Paginated list of nodes


User Management

create_user

Create a user account.

Parameters:

Name Type Required Description
mail string Yes Email address
name string Yes Username
pass_ string No Password
status boolean No Active status (default: true)
roles list[string] No Role machine names

Returns: Created user data


DevOps

drush_command

Execute any Drush command.

Parameters:

Name Type Required Description
command string Yes Drush command name
args list[string] No Command arguments
options dict No Key-value options

Returns: Command output with return code, data, stderr

Example:

{
  "command": "cache-rebuild",
  "args": [],
  "options": {}
}


Status & Health

health_check

Run four read-only probes — Drush and site status, the database connection, the JSON:API index, and the modules the other tools assume — and get the concrete fix for each failure. Call this first when other tools return opaque connection errors.

Parameters: none

Returns: ok overall, per-probe results (drush, database, jsonapi, modules), and a problems list of {check, problem, hint}

status_report

The site's own status report (what /admin/reports/status shows), with each requirement's title, severity, description, and value. Errors and warnings are returned by default. A failure here is usually the site's requirements checker breaking — the drush error is returned verbatim.

Parameters:

Name Type Required Description
severity_filter string No One of error, warning, info, ok
include_ok bool No Return the whole report, not just problems

Returns: requirements rows, counts per severity, total

database_updates

Pending database updates — read-only, runs nothing. Answers "did the modules I just updated leave schema behind?".

Parameters: none

Returns: pending update rows, count, and a hint to back up and run drush updatedb when any are pending

available_updates

Packages with newer versions available, from composer outdated, grouped into core, contrib, and other. Dev dependencies are excluded unless include_dev is set (composer marks none of them itself, so they are filtered via composer.json's require-dev). With security_only, the list is intersected with composer audit and the advisories are attached.

Parameters:

Name Type Required Description
include_dev bool No Keep dev dependencies in the report
security_only bool No Only outdated packages with a security advisory

Returns: core, contrib, other package rows, total, dev_filtered, security_only

config_status

Compare active configuration with the exported sync directory — read-only, nothing is exported or imported. An empty sync directory shows everything as "Only in DB", which the tool calls out.

Parameters: none

Returns: counts and objects per state (Same, Only in DB, Different, …), total


Site Insight

find_entity_references

Which bundles use reference fields targeting an entity type — "where are tags used?" answered from field configuration. Filter by referencing bundle or field_name. This reports where references can live, not which rows point where; for the data, use db_query.

Parameters:

Name Type Required Description
entity_type string Yes Target type, e.g. taxonomy_term, media
bundle string No Only fields on this bundle
field_name string No Only this field
limit int No Rows to return (1–500, default 50)

Returns: reference_fields rows, by_source_entity_type counts

search_entities

Case-insensitive substring search across node titles, user names and emails, taxonomy term names, comment subjects, media names, and file names — one read-only LIKE query per type, with the term escaped. Pass entity_types to search fewer tables on large sites; node bodies are not searched (use search_api for that).

Parameters:

Name Type Required Description
query string Yes 1–64 characters
entity_types list[string] No Subset of node, user, taxonomy_term, comment, media, file
limit int No Max rows per type (1–100, default 20)

Returns: results grouped by type, matches, total, and skipped for tables that do not exist on the site

find_entity_by_path

Resolve a URL path or alias (/about, /node/123, or a full URL) to its entity. Internal routes are read directly; anything else goes through the path alias table, then the resolved target is parsed the same way.

Parameters:

Name Type Required Description
path string Yes Path, alias, or full URL (max 512 chars)

Returns: found, the resolved internal_path, entity_type, entity_id, the full entity resource, and the alias row when one was used


Exports

Bulk inventories written to a file: the tool returns only the path, row/column counts, file size, and a three-row preview, so a 5,000-node export never travels through the conversation. Data comes from JSON:API pagination (newlines and accents survive intact), and the destination is confined to the Drupal root, the system temp directory, or your home directory — never anywhere else. Entries with no internal id — Drupal's uid-0 anonymous user is the usual one — are skipped and counted in the response's skipped_without_id field.

export_nodes

Parameters:

Name Type Required Default Description
content_type string No — Limit to one bundle (e.g. 'article')
include_unpublished boolean No False Also export unpublished nodes
include_fields boolean No False Add a fields column of remaining values as JSON (capped at 5000 chars per value)
limit integer No 0 Rows to write (0 = no cap, max 100000)
output_path string No — Destination .csv/.xlsx; defaults to {Drupal root}/exports/ or /tmp/drupal-mcp-exports/
format string No csv csv (UTF-8 with BOM) or xlsx

Returns: file_path, rows, columns, file_size_kb, preview (first 3 rows), filters, truncated (row/page cap stopped the export)

Errors: - error — invalid bundle/format/limit, a path outside the safe roots, or no JSON:API client

export_users / export_media / export_taxonomy

Same contract per entity: export_users includes blocked accounts (their status column says so) plus role labels; export_media adds bundle, owner, and the managed file's filename/URI, with a media_type filter; export_taxonomy adds usage_count, the used_in fields, and a safe_to_delete verdict computed from one COUNT query per field storage targeting taxonomy terms (vocabulary filter, include_usage=false to skip the counts). All four accept format="xlsx" for an Excel workbook.

Theme Analysis

Read-only theming inspection, the counterpart of the theme_dev tools that create things. Theme metadata comes from drush pm:list plus a YAML parse of the theme's own info.yml, block placements from the block--block JSON:API collection, and template walks resolve every path inside DRUPAL_ROOT first — symlinks and .. segments that leave the docroot are rejected before any read. Tools that inspect files say so in their error when DRUPAL_ROOT is not configured.

theme_active

Parameters: (none)

Returns: default, admin (from system.theme), enabled (name, label, package, path, version per theme), enabled_count, disabled_count

Errors: - error — Drush not available, or the theme list came back empty

theme_info / theme_regions

Parameters:

Name Type Required Default Description
theme_name string Yes — Theme machine name (e.g. 'olivero')

Returns: theme_info merges pm:list (status, version, path) with the parsed info.yml: label, description, core_version_requirement, hidden, regions (in declaration order), libraries, dependencies, and base_theme — the chain of parents followed upward as far as the site allows, each with found: false when a parent is not installed. theme_regions returns each region with block_count and its blocks (id, label, plugin, weight, status), total_blocks, and blocks_in_unknown_regions (placements whose region the info.yml no longer defines — they will not render).

Errors: - error — invalid machine name, theme not installed (with available), its directory or info.yml missing under DRUPAL_ROOT, or no JSON:API client (theme_regions needs one for placements)

theme_blocks

Parameters:

Name Type Required Default Description
theme_name string No — Only this theme's placements
region string No — Only this region (e.g. 'sidebar')
search string No — 1–64 chars; case-insensitive substring of label or plugin

Returns: blocks (id, theme, region, label, plugin, weight, status, visibility_rules count), total, filters — sorted by theme, region, weight, label

Errors: - error — invalid identifier, empty/oversized search, or no JSON:API client

theme_templates / theme_template_overrides

Parameters:

Name Type Required Default Description
theme_name string Yes — Theme machine name
pattern string No — theme_templates only: 1–64 char case-insensitive substring of the template name (e.g. 'node--', 'views')

Returns: theme_templates gives count and templates (docroot-relative path + bytes) plus truncated when the walk hit its file cap. theme_template_overrides indexes every Twig file in the docroot once (excluding the theme itself) and splits the theme's templates into overrides (same-named core/module files it shadows, with their sources) and theme_only (theme originals), alongside docroot_templates_scanned.

Errors: - error — invalid machine name, bad pattern, theme not installed, its directory missing, or DRUPAL_ROOT not configured

template_suggestions

Parameters:

Name Type Required Default Description
entity_type string Yes — e.g. 'node', 'block', 'taxonomy_term', 'user', 'field', 'page'
bundle string No — e.g. 'article'; unknown entity types still get the generic chain

Returns: suggestions most-specific first (bracketed parts are placeholders Drupal fills in — node--article--123.html.twig beats node--article.html.twig), each with a description and in_checked_theme: whether the default theme already ships that file, so you know which name creating one would take effect. checked_in names the theme that was checked; when DRUPAL_ROOT is unset the check is skipped and a note says so instead of guessing.

Errors: - error — invalid entity_type or bundle

view_template_info

Parameters:

Name Type Required Default Description
view_name string Yes — View machine name (from views_list)
display_id string No — Display machine name; without it every display gets a suggestion

Returns: label and displays from the JSON:API view collection (the view's drupal_internal__id is the machine name, and the embedded display dict is the real one — Views config names differ between Drupal generations, view.* on older sites and views.view.* on Drupal 11.4+, so the entity collection is the stable source), then suggestions (views-view--NAME--DISPLAY → views-view--NAME → views-view, marked in_checked_theme against the default theme when DRUPAL_ROOT allows) and checked_in.

Errors: - error — invalid identifier, no JSON:API client, view not found (with the available views the site has), or an unknown display_id (with the displays the view has)

Security Scanners

Zero-dependency local analysis: PHP/JS/Drupal files are matched against a curated pattern registry with Drupal-aware false-positive rules, so a site without PHPStan (which security_scan needs) still gets concrete findings. Targets are confined to DRUPAL_ROOT — symlinks and escaping paths are rejected, and vendor/, node_modules/, tests/, dist/, and contrib/ are pruned from the default scan.

code_security_scan

Parameters:

Name Type Required Default Description
module string No — Module machine name (e.g. 'webform'); exclusive with path
path string No — Directory relative to DRUPAL_ROOT (e.g. 'themes/custom/mytheme')
categories array No all Registry keys: 'xss', 'sql_injection', 'command_injection', 'path_traversal', 'hardcoded_secrets', 'access_control', 'csrf', 'deprecated_api'
severity string No — high, medium, or low — only that level
max_findings integer No 50 Rows returned (1–500), highest severity first

With no target, the site's own modules/ and themes/ directories are scanned (contrib and core excluded).

Returns: findings (file, line, category, pattern, severity, description, recommendation, trimmed snippet), counts (by_category/by_severity cover the whole run even when findings truncates), files_scanned, false_positives_filtered (EntityQuery conditions, stream wrappers, escapeshellarg, comments with example secrets, and similar safe APIs are recognized), truncated, and a note when rows were cut.

Errors: - error — both module and path, an unknown category (with available), a bad severity or max_findings, a module/path not found inside DRUPAL_ROOT, or no DRUPAL_ROOT configured

route_access_audit

Parameters: same target shape as code_security_scan (module or path, defaulting to the site's own code).

Returns: routes — every route from every *.routing.yml with its name, route path, controller, controller_file (the file declaring the class, when it can be found), and an access classification: anonymous (access: TRUE), permission:NAME, role:NAME, entity, custom, denied, or missing — no requirement at all, which is the finding, since Drupal then falls back to whatever the controller does. Plus counts per access kind, anonymous_routes, routes_missing_access, and parse_errors for unreadable YAML.

Errors: - error — both targets passed, module/path not found inside DRUPAL_ROOT, or no DRUPAL_ROOT configured