WP-CLI execution

New in v3.4.0. Free, ships disabled by default. Lets a connected agent run wp-cli commands directly, synchronously for quick lookups, or as a detached background job for long migrations and bulk tasks.

Not the same as the WP-CLI connection guide

Connecting via WP-CLI covers using wp mcp-adapter serve as a transport to connect an MCP client to your site. This page is the reverse: a connected agent running wp-cli commands as one of its tools. Different pages, different direction.

Risk notice

WP-CLI is powerful and, via the shell path, is effectively command execution. Every command passes a blocklist validator (no eval, eval-file, shell, raw db query, config writes, package install, or arbitrary PHP flags) and runs with argv arrays, no shell interpolation. All four tools require manage_options, ship disabled by default, and every run is recorded to the change ledger.

Tools

emcp-tools/run-wp-cli

Runs a command synchronously and returns stdout, stderr, and the exit code. Runs in-process over the WP-CLI stdio transport, or via a configured wp binary over HTTP.

Input: command (required) is the command without the leading wp (e.g. "plugin list --format=json"). timeout sets the max seconds on the shell path, default 60, max 300.

emcp-tools/dispatch-wp-cli

Runs a command as a detached background job, for long migrations or bulk tasks, and returns a job id. Requires a configured wp base command. Poll it with get-wp-cli-job.

Input: command (required). timeout sets the advisory max seconds, default 900.

emcp-tools/get-wp-cli-job

Returns a background job’s status (running / completed / failed), exit code, and captured stdout/stderr. Read-only.

Input: job_id (required).

emcp-tools/list-wp-cli-jobs

Lists background jobs. Read-only.

Setting the WP-CLI command

Over HTTP, run-wp-cli and dispatch-wp-cli need to know how to start WP-CLI on your server. Set it on EMCP Tools → Connection → 3rd-party services, in the WP-CLI card, field WP-CLI command (for example wp, or php /path/to/wp-cli.phar), then choose Save changes. Leave it empty to run the tools in-process only, which works when the agent is connected over the WP-CLI stdio transport. The EMCP_TOOLS_WPCLI_COMMAND constant in wp-config.php also sets it, and the field then shows “Set in wp-config.php”.

Enabling these tools

All four are off until enabled on EMCP Tools → Tools: go to the WordPress tab, find the WP-CLI section, switch on the ones you want, then choose Save changes in the save bar. See Disabling tools. Given the blocklist still allows a wide range of wp-cli subcommands (plugin/theme management, user operations, cron, transients, and more), treat enabling these the same as granting shell-adjacent access, only turn them on for agents and sites you trust.