mcp-wp-cli-terminus 0.3.0

MCP server for WP-CLI over local Docker, Pantheon Terminus, or SSH — run WP-CLI and byte-faithfully copy posts/meta between WordPress environments, with checksum verification.

mcp-wp-cli-terminus

An MCP (Model Context Protocol) server that lets Claude and other AI agents run WP-CLI against WordPress — over local Docker, Pantheon Terminus, or SSH — and byte-faithfully copy posts and post meta between environments with checksum verification.

Built for developers using Claude Code / Claude Desktop (or any MCP client) to operate WordPress sites — including Pantheon multidevs reached through Terminus — without hand-assembling fragile wp eval commands.

_{wp-cli · wordpress · terminus · pantheon · mcp · model-context-protocol · claude · claude-code · anthropic · wordpress-migration · devops}

---

Why

Moving a WordPress post's body or custom fields between environments (e.g. pushing a block-based front page from local to a Pantheon multidev) is deceptively hard to do correctly:

• wp post update --post_content truncates at newlines (wp-cli#2712).
• Piping content over STDIN hangs on terminus remote:wp (terminus#1615).
• Hand-pasting base64 into an agent prompt is lossy — a single flipped byte silently corrupts production.
• Large payloads passed as one shell argument hit the Linux MAX_ARG_STRLEN (131072 bytes) limit and fail with E2BIG.
• Post meta with serialized arrays / multiple values per key is easy to corrupt by re-serializing.

This server solves all of that: content is read, base64-encoded in code, delivered over a transport-safe path, and then re-read and checksum-compared to the source. A mismatch is reported, never silently trusted.

Tools

Tool	What it does
wp_init_config	Guided setup: detects your Docker container, WordPress path, and Terminus site, then writes .serena/wp-cli.conf (asking you for anything it can't detect).
wp_cli	Run any WP-CLI command against a configured site — target: local (Docker) or target: production (Terminus or SSH, chosen by config). Destructive commands are guarded on production.
wp_sync_post	Sync a post's post_content onto the same post ID in another environment (updates an existing post; e.g. a multidev cloned from the same DB), with an md5 round-trip verification.
wp_sync_post_meta	Sync a post's complete meta (serialized arrays, multiple values per key, ACF repeaters) onto the same post ID in another environment, with a canonical checksum verification. All keys (full mirror) or an allow-list.
wp_clone_post	Clone a post to another environment as a NEW post — the destination assigns its own ID (returned as new_id). Use when the post doesn't exist on the destination yet. Copies fields + all meta, verifies, and reports meta keys that hold ID references for manual remapping.

Sync vs. clone

• Sync (wp_sync_post, wp_sync_post_meta) updates an existing post that shares the same ID on both sides — the right tool when the environments were cloned from the same database (a Pantheon multidev, a staging copy). It fails if the destination ID doesn't exist.
• Clone (wp_clone_post) creates a new post on the destination from a source post; the destination assigns a fresh ID. Use it when the content is new to the destination (e.g. pushing a locally-authored post/alert up to a multidev). Meta values that look like ID references (_thumbnail_id, ACF relationship/image fields) are copied verbatim and reported — never silently remapped across databases.

Correctness guarantees

• Never routes content through the model's text. Payloads are read into the server and base64-encoded in code.
• Checksum-verified. Every sync/clone re-reads the destination and compares it to the transferred source; verified: false + an error on any mismatch.
• Transport-agnostic. The same logic runs over local Docker, Pantheon Terminus, and WP-CLI --ssh.
• Large payloads. Docker/SSH deliver PHP over STDIN (wp eval-file -, exempt from the argv size limit); Terminus uses a size-guarded argv path and fails loud rather than emitting a raw E2BIG.
• Meta fidelity. Values are round-tripped so WordPress's own maybe_serialize() reproduces the exact stored meta_value — arrays stay arrays, and strings that merely look serialized stay strings.
• Production guard. Writes to a production destination require confirm: true when PROD_GUARD is enabled.

Install & run

The server is pure Python (stdlib only, zero dependencies).

With uvx (recommended — no install)

// Claude Desktop / Claude Code MCP config
{
  "mcpServers": {
    "wp-cli": {
      "command": "uvx",
      "args": ["mcp-wp-cli-terminus"]
    }
  }
}

With pip

pip install mcp-wp-cli-terminus

{
  "mcpServers": {
    "wp-cli": { "command": "mcp-wp-cli-terminus" }
  }
}

From source

git clone https://github.com/EarthmanWeb/mcp-wp-cli-terminus
cd mcp-wp-cli-terminus
python -m wp_cli_mcp   # PYTHONPATH=src, or `pip install -e .`

Configure

Guided setup with wp_init_config (recommended)

The easiest way to create the config is to ask your MCP client to run the wp_init_config tool. It works in two phases:

1. Detect — called with no arguments, it probes the environment (running Docker containers, the WordPress path inside them, and any authenticated Pantheon Terminus site) and reports what it found plus a list of anything it couldn't determine.
2. Write — the agent asks you for whatever was missing, then calls it again with write=true to save <project-root>/.serena/wp-cli.conf.

Just tell your agent: "set up the wp-cli config for this project" — it will call wp_init_config, fill in what it can, ask you for the rest, and write the file (it won't overwrite an existing config unless you say so).

Manual setup

The server reads <project-root>/.serena/wp-cli.conf at runtime (set CLAUDE_PROJECT_DIR to point at your project). Copy wp-cli.conf.example and edit:

DEFAULT_SITE=example-site
PROD_GUARD=true

[site:example-site]
LOCAL_CONTAINER=my-container       # docker container running WP-CLI
LOCAL_PATH=/var/www/html           # WordPress path inside the container
TERMINUS_SITE=example              # Pantheon site — production routes over Terminus
TERMINUS_ENV=dev                   # default env (override per call)
# — or, for a non-Pantheon remote, omit TERMINUS_* and set:
# REMOTE_SSH=[e-mail]:22/var/www/html

• Production transport is chosen by config: TERMINUS_SITE → terminus remote:wp; otherwise REMOTE_SSH → WP-CLI --ssh.
• Multi-site: add more [site:NAME] sections and pass site per call.

Never commit .serena/wp-cli.conf — it may contain hostnames/SSH strings. The shipped .gitignore excludes it.

Usage examples

// Run a WP-CLI command locally
{ "tool": "wp_cli", "args": "plugin list --status=active --format=json" }

// Run against production (Terminus or SSH per config)
{ "tool": "wp_cli", "args": "option get siteurl", "target": "production" }

// SYNC a front page's block markup onto the SAME post ID on production, verified
{ "tool": "wp_sync_post", "post_id": 42, "from": "local", "to": "production", "confirm": true }

// SYNC ALL meta for a post (full mirror) onto the same ID, verified
{ "tool": "wp_sync_post_meta", "post_id": 42, "from": "local", "to": "production", "confirm": true }

// SYNC only specific meta keys
{ "tool": "wp_sync_post_meta", "post_id": 42, "from": "local", "to": "production",
  "keys": ["_thumbnail_id", "my_field"], "confirm": true }

// CLONE a locally-authored post to production as a NEW post (returns new_id)
{ "tool": "wp_clone_post", "post_id": 268529, "from": "local", "to": "production", "confirm": true }

// Clone but force the new post to draft
{ "tool": "wp_clone_post", "post_id": 268529, "from": "local", "to": "production",
  "overrides": { "post_status": "draft" }, "confirm": true }

wp_sync_* return verified: true/false with src_md5 / dst_md5, the delivery mode, and per-side transport. wp_clone_post returns new_id, verified, content_verified, meta_verified, and id_reference_keys (meta keys to review).

Debug logging

Failures (non-zero WP-CLI exits) are appended to a log in your system temp dir — failures only, successes are never logged:

• Location: ${TMPDIR}/wp-cli-mcp/failures.log (override with WP_CLI_MCP_LOG_DIR).
• Disable entirely with WP_CLI_MCP_LOG=0.
• SSH connection strings are redacted in the log.

Requirements

• Python 3.8+
• WP-CLI reachable via one of: a local Docker container (docker exec), Pantheon Terminus on the host, or a host WP-CLI with --ssh.

Tests

python -m unittest discover -s tests -v

70 stdlib-only unit tests (split by area under tests/) cover config parsing, transport selection (local/Terminus/SSH), the argv size guard, newline handling, PHP-key safety, id-reference detection, and the full sync/clone/verify orchestration via an injectable command-runner seam (no real WP-CLI invoked).

Releasing

Releases publish to PyPI automatically via GitHub Actions (.github/workflows/publish.yml) using PyPI Trusted Publishing — no API token is stored in the repo. The workflow builds, runs the tests, and uploads on every published GitHub Release.

One-time setup (per project, on PyPI):

1. On PyPI, open the project → Publishing → Add a new publisher → GitHub, with:
   • Owner: EarthmanWeb · Repository: mcp-wp-cli-terminus
   • Workflow name: publish.yml · Environment: pypi
2. (Optional) In GitHub repo Settings → Environments, create an environment named pypi to gate/approve publishes.

Cut a release (this triggers the publish):

# 1. Bump the version in pyproject.toml (e.g. 0.1.0 -> 0.1.1), commit, push.
# 2. Tag + create the GitHub Release — the workflow does the rest:
gh release create v0.1.1 --title "v0.1.1" --notes "What changed"

The action then builds, tests, and publishes mcp-wp-cli-terminus to PyPI. Within ~a minute uvx mcp-wp-cli-terminus (and the SWE plugin launcher) pick up the new version. You can also run it manually from the Actions tab (workflow_dispatch).

First release was published manually with uv build && uv publish; subsequent releases use the workflow above.

License

MIT