@wootsup/yt-builder-mcp. YT Builder MCP for YOOtheme Pro (unofficial)

Drive your page builder via MCP. Built for YOOtheme Pro 4.0+ on WordPress and Joomla 5/6. Connect Claude Desktop, Claude Code, Cursor, Zed, Continue, Cline, Roo Code, Codex CLI, or Gemini CLI in one command.

Independent third-party project. YOOtheme® is a registered trademark of YOOtheme GmbH (yootheme.com). YT Builder MCP is built by WootsUp (getimo productions) and is not affiliated with, endorsed by, or sponsored by YOOtheme. The integration uses YOOtheme Pro's public extension points.

License: MIT

Quick start

# 1. Install the host plugin for your CMS.
#    WordPress: yt-builder-mcp-*.zip plugin.
#    Joomla 5/6: pkg_ytbmcp-*.zip package (three sub-extensions in one go).
#    See https://github.com/wootsup/yt-builder-mcp/releases

# 2. Generate a Bearer key.
#    WordPress: wp-admin → Tools → "YT Builder MCP" → Bearer Keys.
#    Joomla:    Administrator → Components → "YT Builder MCP" → Bearer Keys.
#    Key format: ytb_(live|test)_<payloadB64Url>.<sigB64Url>
#    The key is shown ONCE. Copy it now; it cannot be recovered later.

# 3. Run the wizard to configure your AI client(s):
npx -y @wootsup/yt-builder-mcp setup

# 4. (Optional) Install the bundled agent skill:
npx -y @wootsup/yt-builder-mcp install-skill

# 5. Restart your AI client.

The wizard prompts for:

1. Your site URL (WordPress or Joomla).
2. The Bearer key you just generated.
3. Which AI client(s) to configure (multi-select).

It probes the host plugin's /health endpoint (/wp-json/yt-builder-mcp/v1/health on WordPress, /api/index.php/v1/yt-builder-mcp/health on Joomla) to confirm the plugin is reachable, then /etag to validate the Bearer key. After restart you should see the new tools prefixed with yootheme_builder_*.

Supported AI clients

The wizard auto-detects and configures the following clients:

| Client | Config path | Notes | |--------|-------------|-------| | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) | MCPB bundle also supported (see below) | | Claude Code | ~/.claude.json | | | Cursor | ~/.cursor/mcp.json | | | Zed | ~/.config/zed/settings.json | | | Continue | ~/.continue/config.json | | | Cline | ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json | VS Code extension | | Roo Code | same VS Code globalStorage path under rooveterinaryinc.roo-cline | VS Code extension | | Codex CLI | ~/.codex/config.toml | | | Gemini CLI | ~/.gemini/settings.json | |

Tool surface (gateway model)

The server catalogues 60 tools + 2 gateways = 62 reachable end-to-end, of which 49 are advertised in tools/list (well under Cursor's ~40-tool cap — the 3-lane split keeps the advertised surface small while every catalogued tool stays callable):

• 2 direct top-level tools (always in tools/list): yootheme_builder_health, yootheme_builder_diagnose. The "the gateway itself might be broken" escape hatch.
• 45 essential forwarded tools (always in tools/list): the most-used reads and writes (pages_list, pages_create, pages_delete, pages_set_status, pages_restore (the one correct way back from the trash — a gateway-only placement would leave it discoverable only to a caller who already knows it exists), page_generate_dynamic, get_etag, element_list, element_add, element_update_settings, sources_list, element_types_list, inspect_multi_items_binding, the multi-site sites_list / sites_test / use_site, get_skill (the full-guide retrieval tool), modules_delete (the one gateway-only destructive tool that removes data outside the layout tree, promoted so a host can gate it individually), and the bind→save→publish→unbind chain element_bind_source / page_save / page_publish / element_unbind_source, among others).
• 2 gateway tools exposing the remaining 13 advanced tools:
  • yootheme_builder_advanced (write-capable) routes all 13 (clean_implode_directives, inspect_sublayout, layout_query, library_save_as, library_delete, local_content_types, local_content_read, pages_audit, heading_outline, navigation, header_transparency_set, modules_update, modules_create).
  • yootheme_builder_advanced_read (read-only-annotated) routes only the 7 read-only advanced tools (inspect_sublayout, layout_query, local_content_types, local_content_read, pages_audit, heading_outline, navigation), so MCP hosts can auto-allow pure inspection without a per-call write-approval prompt. Call yootheme_builder_advanced({ tool: "<name>" }) for discovery (returns the schema) or ({ tool, arguments }) to execute.

See skills/yt-builder-mcp/SKILL.md for the full catalog and canonical workflows, and docs/TOOL-CATALOG.md for an auto-generated, per-tool reference (regenerated from the live registry by node scripts/extract-tools.mjs — never hand-copied here, which is exactly why the numbers above stay accurate release over release; an earlier, hand-maintained domain-count table on this exact spot had drifted to less than half the real tool count and a stale gateway count before it was replaced with this pointer).

All tool names are prefixed with yootheme_builder_ at the MCP server boundary.

Subcommands

yt-builder-mcp setup            Interactive first-run wizard (default).
yt-builder-mcp doctor           Diagnose connectivity (Node version, corporate
                                 proxy/TLS, site reachability, bearer validity,
                                 update status). Run this first when setup "hangs".
yt-builder-mcp install-skill    Install the bundled agent skill.
yt-builder-mcp uninstall        Remove yt-builder-mcp from configured AI clients
  (alias: remove)               (and, optionally, the installed skill).
yt-builder-mcp add-site         Add a site to the multi-site registry (see
                                 "Multi-site setup" below).
yt-builder-mcp list-sites       List configured sites (no network calls).
yt-builder-mcp remove-site <id> Remove a site; auto-promotes the next as default.
yt-builder-mcp set-default <id> Flip which configured site is the default.
yt-builder-mcp test-site <id>   Probe /health + /etag for one configured site.
yt-builder-mcp --version, -v    Print package version.
yt-builder-mcp --help, -h       Show usage.

install-skill (bundled agent skill)

Copies the bundled skills/yootheme-builder/ folder into ~/.claude/skills/ and appends a marker block to ~/AGENTS.md so other AI clients pick it up automatically.

~/.claude/skills/ is the universal marker path recognised by Claude Desktop and (per the same convention as @wootsup/apimapper-mcp) other AI clients that follow the ~/AGENTS.md discovery protocol. The single location keeps the skill discoverable across every supported client without per-client write logic.

The skill ships with the 6 canonical workflows (build hero, bind source, clone section, diagnose 401, add custom element, SEO audit) plus a 60-tool auto-generated catalog appendix.

MCPB bundle (Claude Desktop one-click install)

The repo includes a manifest.json and scripts/build-mcpb.js that produces a yt-builder-mcp.mcpb archive, the MCP Bundle (MCPB) format used by Claude Desktop for one-click MCP installs. Build it from a source checkout:

npm run build:mcpb
# → ./yt-builder-mcp.mcpb

Drop the .mcpb file onto Claude Desktop's Extensions screen to install. The bundle includes the compiled dist/, the bundled skill, and manifest.json.

Environment variables

When launched by an AI client (or directly):

| Variable | Required? | Purpose | |----------|-----------|---------| | YTB_MCP_SITE_URL | Yes | Host CMS base URL (e.g. https://example.com). Works for BOTH WordPress and Joomla. Trailing slash is stripped. | | YTB_MCP_WP_URL | No (deprecated) | Legacy alias for YTB_MCP_SITE_URL. Still honoured for older WordPress-only configurations. A non-fatal deprecation notice is written to stderr when this is used without YTB_MCP_SITE_URL. | | YTB_MCP_BEARER_TOKEN | Yes | Bearer key from wp-admin (WordPress: Tools → "YT Builder MCP") or Administrator → Components → "YT Builder MCP" (Joomla). Format-checked client-side: must match ytb_(live\|test)_<payload>.<sig>. Do not prepend Bearer . The MCP server adds it. | | YTB_MCP_PLATFORM | No | Explicit platform hint: wordpress or joomla. Set to joomla when YTB_MCP_SITE_URL is an origin-only Joomla URL (no /api/index.php/ in the path). Defaults to URL-shape auto-detection. | | YTB_MCP_TIMEOUT_MS | No | REST timeout (default 15000). | | YTB_MCP_TEST_MODE | No | 1 skips the stdio loop (smoke tests). | | YTB_MCP_SITES_FILE | No | Path to the multi-site registry (see "Multi-site setup" above). Defaults to ~/.config/yt-builder-mcp/sites.json. | | YTB_MCP_PROFILE | No | Boots the server pinned to one site_id from the registry, for a one-MCP-entry-per-site setup. | | YTB_MCP_EXTRA_HEADERS | No | Extra HTTP headers merged into every outbound request (a WAF cookie, a corporate gateway secret, HTTP Basic-Auth, …). Either a JSON object ({"X-WAF-Token":"abc"}) or Name: value lines. An Authorization entry here is always dropped — the Bearer owns that header. | | YTB_MCP_SITE_BASIC_AUTH | No | user:pass for a site fronted by an HTTP Basic-Auth realm. Sent as the Authorization: Basic … header; the plugin Bearer then travels on X-Authorization. | | YTB_MCP_VERSION | No | Version-pin fallback used when --pin isn't passed at setup time (see "Corporate TLS interception / air-gapped installs"). |

Manual MCP config (no wizard)

For users who don't want to run the wizard, paste this into your AI client's MCP config file:

{
  "mcpServers": {
    "yt-builder-mcp": {
      "command": "npx",
      "args": ["-y", "@wootsup/yt-builder-mcp"],
      "env": {
        "YTB_MCP_SITE_URL": "https://example.com",
        "YTB_MCP_BEARER_TOKEN": "ytb_live_…"
      }
    }
  }
}

For a Joomla install at an origin-only URL, also set the platform hint:

"env": {
  "YTB_MCP_SITE_URL": "https://example.com/joomla",
  "YTB_MCP_BEARER_TOKEN": "ytb_live_…",
  "YTB_MCP_PLATFORM": "joomla"
}

Multi-site setup (more than one WordPress/Joomla site)

Instead of one env block per AI client, add every site once to a shared on-disk registry and address each by site_id:

npx -y @wootsup/yt-builder-mcp add-site \
  --url https://shop.example.com --token "$YTB_TOKEN" \
  --label "Shop" --site-id shop --default

npx -y @wootsup/yt-builder-mcp add-site \
  --url https://blog.example.com --token-ref "op://Vault/blog/token" \
  --label "Blog" --site-id blog

npx -y @wootsup/yt-builder-mcp list-sites
npx -y @wootsup/yt-builder-mcp test-site shop
npx -y @wootsup/yt-builder-mcp set-default blog
npx -y @wootsup/yt-builder-mcp remove-site blog

add-site flags:

| Flag | Required? | Description | |------|-----------|-------------| | --url <site-url> | Yes | Site base URL (WordPress or Joomla). | | --token <bearer> | One of these two | Plain Bearer key. Mutually exclusive with --token-ref. | | --token-ref <op://…> | One of these two | 1Password Secret Reference (op://<vault>/<item>/<field>) instead of a plain-text key. | | --platform auto\|wordpress\|joomla | No (default auto) | Explicit platform hint; auto is runtime-detected on first use. | | --label "<text>" | No | Human-readable label shown by list-sites. | | --site-id <slug> | No (default default) | Registry key used by every other multi-site command and by a tool call's optional site_id argument. | | --default | No | Mark this site as the default (the first added site becomes default automatically). | | --yes | No | Overwrite an existing site_id instead of failing. | | --sites-file <path> | No | Registry file to write, overriding YTB_MCP_SITES_FILE / the default path for this one call. |

The registry lives at ~/.config/yt-builder-mcp/sites.json ($XDG_CONFIG_HOME/yt-builder-mcp/sites.json when that variable is set). YTB_MCP_SITES_FILE is the switch that makes the server READ a registry at all: without it the server ignores sites.json entirely and runs off the single-site YTB_MCP_SITE_URL / YTB_MCP_BEARER_TOKEN pair. setup writes it for you, pointing at the registry it filled; set it by hand only to name a different path. When the file it names is missing or holds no sites, the server falls back to the single-site pair, so an unpopulated registry never costs you a working config. YTB_MCP_PROFILE=<site_id> boots the server pinned to one site from the registry — useful when you'd rather run one MCP entry per site than one shared multi-site entry.

uninstall (alias remove) accepts --all (every detected client + the skill, no prompts), --yes/-y (skip the final confirmation), --keep-skill (remove client entries but leave the installed skill in place), and --force.

Non-interactive CI usage

For scripted / CI installs, pass the answers as flags and add --non-interactive to skip every prompt. Missing required flags exit with code 2 and a clear error to stderr:

npx -y @wootsup/yt-builder-mcp setup \
  --non-interactive \
  --client cursor --client claude-desktop \
  --url https://your-site.example/wordpress \
  --token "$YTB_TOKEN"

Supported flags:

| Flag | Required? | Description | |------|-----------|-------------| | --non-interactive | Yes | Opt-in to non-interactive mode (no prompts). | | --url <site-url> | Yes | Site base URL (WordPress or Joomla). Trailing slash is stripped. | | --token <bearer> | Yes | Bearer key from the host plugin's admin UI (do not prepend Bearer ). | | --client <id> | Yes (≥1) | Client id; repeatable. Valid ids: claude-desktop, claude-code, cursor, zed, continue, cline, roo-code, codex-cli, gemini-cli. |

The wizard still runs its plugin-health + auth probes and uses the exit codes documented in the table below, so CI can branch on the exit code to detect whether the install actually succeeded.

Corporate TLS interception / air-gapped installs

| Flag | Description | |------|-------------| | --ca <path> | Trust a corporate root CA .pem (writes NODE_EXTRA_CA_CERTS=<path> into the generated client config). | | --use-system-ca (or --ca=system) | Trust the OS certificate store instead of an exported file — zero-export, needs Node ≥ 22.15 (writes NODE_OPTIONS=--use-system-ca). | | --pin <version> | Pin the generated client config to an exact version (npx -y @wootsup/yt-builder-mcp@<version>) instead of the floating @latest. Falls back to the YTB_MCP_VERSION env var when omitted. |

The interactive wizard auto-offers --ca / --use-system-ca the moment a probe fails with a TLS-inspection certificate error, so these flags are mainly for the non-interactive/CI path.

One-click setup (pickup mode)

The host plugin's admin UI can hand the wizard a freshly-minted Bearer key directly, skipping the URL/token prompts entirely:

npx -y @wootsup/yt-builder-mcp setup \
  --pickup https://example.com/wp-json/yt-builder-mcp/v1/setup/pickup \
  --nonce "$NONCE" \
  --client claude-desktop

The pickup URL and nonce are revealed together in wp-admin → Tools → "YT Builder MCP" (WordPress) or Administrator → Components → "YT Builder MCP" (Joomla). The pickup is IP-bound, single-use, and expires after 5 minutes; any --url/--token passed alongside --pickup are ignored (with a stderr warning).

Exit codes (CLI)

The CLI returns POSIX-style exit codes for scripting / CI:

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Invalid input / unknown subcommand | | 2 | Health probe failed and user declined to continue (or install-skill failure) | | 3 | Auth probe failed and user declined to continue | | 4 | Write failed; configs rolled back | | 5 | Handshake failed; configs rolled back | | 6 | AI clients configured, but the site could not be recorded in sites.json; nothing rolled back | | 99 | Unhandled fatal in dispatcher | | 130 | User cancelled (SIGINT) |

Documentation

• SKILL.md (bundled agent skill): 6 canonical workflows, gateway model, tool catalog
• REST API Reference
• MCP Tool Reference

Repository

https://github.com/wootsup/yt-builder-mcp