YOOtheme MCP — documentation

YOOtheme MCP · WordPress & Joomla · Documentation

YOOtheme MCP / CLI / Skill — documentation

Manage YOOtheme Pro 5.x layouts, the Style Customizer, custom CSS/JS, the cookie consent manager and saved element presets on your WordPress and Joomla 4/5 sites — from a terminal or an AI assistant. It talks to each site over its standard REST API: no plugins, no MU-plugins, no SSH, no file access on the server. Just an Application Password (WordPress) or an API Token (Joomla).

What it is

One package, three front-ends over the same REST code:

• CLI — yootheme …, the recommended entry point for daily ops, scripts and CI.
• MCP server — yootheme-mcp / python -m yootheme_mcp, the same logic exposed to Claude Desktop or Cursor so an agent can manage your sites in chat.
• Skill yootheme-remote — an agent playbook that knows the tools and the safe order to use them in.

Sibling products: elementor-mcp (Elementor, WordPress) and gmcbuilder-mcp (GMC Builder). Target tested: YOOtheme Pro 5.0.37.

Requirements

• Python 3.10+ on your machine (Windows, macOS or Linux). The CLI works on its own; the MCP needs a chat client that speaks MCP.
• Sites running YOOtheme Pro 5.x on WordPress or Joomla 4/5.
• A WordPress Application Password, or a Joomla API Token, per site. Nothing is installed on the server.

Install

cd yootheme-mcp
python -m venv .venv
.venv\Scripts\Activate.ps1        # PowerShell (Linux/macOS: source .venv/bin/activate)
pip install -e .

yootheme --version

After install you have the yootheme CLI and the yootheme-mcp server entry point. On Windows there is also a one-shot INSTALL.ps1.

Site credentials

WordPress — Application Password

1. WP Admin → Users → your profile → scroll to Application Passwords.
2. Name it yootheme-cli → Add New Application Password.
3. Copy the value (xxxx xxxx xxxx xxxx xxxx xxxx) — shown once, keep the spaces.

Your normal login password does not work for the REST API. Application Passwords are core to WordPress since 5.6.

Joomla — API Token

1. Enable the plugins API Authentication – Web Services Joomla Token and User – Joomla API Token.
2. Edit a Super User profile → Joomla API Token tab → Generate.
3. Copy the token as displayed (already base64-encoded).

Configure sites.json

A single file lists every site. On Windows it lives at %APPDATA%\yootheme-mcp\sites.json (Linux/macOS: ~/.config/yootheme-mcp/sites.json), or point YOOTHEME_MCP_CONFIG anywhere.

{
  "sites": {
    "tiserve": {
      "platform": "wordpress",
      "url": "https://tiserve.it",
      "wp_username": "admin33",
      "wp_app_password": "xxxx xxxx xxxx xxxx xxxx xxxx"
    },
    "loquehay": {
      "platform": "joomla",
      "url": "https://loquehay.es",
      "joomla_token": "base64TokenFromUserProfile"
    }
  }
}

yootheme sites                 # list configured sites
yootheme ping tiserve          # verify auth + reachability
yootheme list tiserve --limit 50 --only-with-layout

WordPress layout visibility (optional)

On many WordPress installs YOOtheme does not register _yootheme_page with show_in_rest. The symptom: yootheme list shows your pages but reports LAYOUT=no on every row, because the layout meta is hidden from REST. Three ways to handle it, best first:

1. Use the YOOtheme REST namespace — if the site exposes /wp-json/yootheme/v1/* (most 5.x installs do), the CLI/MCP falls back to it automatically for the customizer and settings.
2. Optional MU-plugin extras/mu-yootheme-rest.php (about 30 lines) registers the meta with show_in_rest=true plus a capability check. Drop it in wp-content/mu-plugins/ to unlock per-page layout read/write.
3. Use the builder UI for per-page layouts and the CLI for everything else — customizer, settings, cookie consent, presets, bulk find/replace.

On Joomla no companion is needed: an article's layout is an HTML comment at the start of fulltext, and a mod_yootheme_builder module stores its tree in content — both reachable through the Web Services API directly.

What you can do

Not exposed on purpose: the Pro cloud preset library, child-theme files (use SFTP), and admin-only UI actions (recompile Less, clear cache, system check).

Customizer & settings by key

YOOtheme Pro serialises the whole Customizer into one config blob (Joomla: the template style's params.config; WordPress: /wp-json/yootheme/v1/style + settings). Read or write any value by its dotted key:

yootheme settings get tiserve --key style          # active style, e.g. "fuse"
yootheme settings get tiserve --key header.layout  # any Layout panel
yootheme settings get tiserve --key custom_less -o custom.less
yootheme settings set tiserve custom_less new-custom.less
yootheme customizer get tiserve -o customizer-backup.json

WordPress caveat. On Joomla the settings and customizer are the same blob, so consent / custom_less / scripts are always reachable. On WordPress they are two different endpoints; if a key shows up only in customizer get and not in settings get --key …, the settings shortcut is reading the wrong store — compare the two before relying on it.

Safety — the destructive paths

Most write commands prompt for confirmation (pass --yes to skip). A few are irreversible on the remote side, so they are guarded:

• A Joomla article's builder layout IS its body. Writing a layout onto an article that already has text would replace that text with no version to restore. set, import and duplicate refuse unless you pass --replace-body (CLI) / replace_body: true (MCP); the replaced text is handed back to you as replaced_body and written beside the layout — nowhere else.
• Delete trashes, destroy is explicit. article delete sends the article to Joomla's trash (recoverable); only --permanent destroys it, and its prompt says so.
• A scripts write cannot silently drop entries. Writing the Scripts / External-Services list refuses to remove entries you omitted, naming them in would_remove; allow_removals: true accepts the loss and returns the removed descriptors. Adding needs no flag.
• bulk-replace --apply rewrites every matching layout on the site. It does not prompt — always read the dry-run report first.

Run as an MCP server

To let Claude Desktop / Cursor call these tools in chat, add:

{
  "mcpServers": {
    "yootheme": {
      "command": "yootheme-mcp",
      "env": {
        "YOOTHEME_MCP_CONFIG": "C:/Users/you/AppData/Roaming/yootheme-mcp/sites.json"
      }
    }
  }
}

Then ask, e.g. "list configured yootheme sites and ping them" or "copy the layout of page 32 on tiserve to article 17 on loquehay".

Licence & updates

Sold through GMC Licenses with a soft licence check. Put your Download Key in %APPDATA%\yootheme-mcp\license.key (one line) or the YOOTHEME_MCP_LICENSE_KEY environment variable. The client code is MIT licensed.

Troubleshooting

FAQ

• Do I have to install anything on the site?

  No. It works entirely over the site's standard REST API with an Application Password (WordPress) or API Token (Joomla). The only optional server-side file is a small WordPress MU-plugin that makes per-page layouts visible to REST — and even that is a convenience, not a requirement.

• WordPress and Joomla at the same time?

  Yes. List both in sites.json with their platform. You can even duplicate a layout from a WordPress page to a Joomla article — the builder JSON is the same on both.

• Can it overwrite an article's text?

  Only if you tell it to. Because a Joomla article's builder layout is its whole body, writing a layout onto an article that has text is refused unless you pass --replace-body, and the replaced text is handed back to you so you can keep it.

• Is there a visual editor?

  No — you keep using YOOtheme's own builder for drag-and-drop. This is a headless toolkit for scripted, repeatable and AI-driven changes: bulk find/replace, customizer edits, presets, cross-site copies and CI.

• Which YOOtheme version does it target?

  YOOtheme Pro 5.x, tested against 5.0.37. The v5.0 features — Cookie Consent Manager, scroll animations, Display Conditions and the rest — are edited through the same layout JSON and settings keys.