WPConvert MCP

@wpconvert/mcp

A Model Context Protocol server for WPConvert.ai. It lets an AI agent (Cursor, Claude Code, Claude Desktop, etc.) convert the current workspace folder into a WordPress theme — no manual zipping required.

It's a thin wrapper over the same HTTP API and smart-zip logic as the wpconvert CLI.

Requires Node.js >= 18. No API key is needed to start: the agent can give you a link for a few free guest previews (one quick human check in the browser, no account), or for signing in. Downloads need Starter, Pro, Agency or pay-as-you-go credits, which you can buy from the same conversation.

Tools

Tool	Purpose
wpconvert_convert_folder	Zip a folder (excluding node_modules, build output, secrets) and start a conversion. Returns a jobId.
wpconvert_check_status	Poll a job's status. Persisted values follow the OpenAPI ConversionStatus enum (queued, pipeline stages, done, failed). The tool-layer bucket processing means still in progress — not a persisted API value.
wpconvert_download_result	Download a completed conversion to disk.
wpconvert_create_preview	Get a WordPress Playground URL to view the theme in a live in-browser WordPress. The link expires after about ten minutes and is sensitive — open it in a browser.
wpconvert_explain_failure	Return the failure reason for a failed job.
wpconvert_quota	Show quota, capabilities, and recommended_next. Call before converting. For a guest session, shows free previews left.
wpconvert_connect	Start a browser link: kind: "guest" (free previews, no account) or kind: "login" (sign in; saves a new API key locally). Returns a link and code for you to open — the agent never opens it.
wpconvert_connect_status	Check whether you finished the link (waits ~20s), and how WPConvert is connected now.
wpconvert_plans	Every option with what it includes and today's price: Starter (one theme), Pro, Agency (monthly/yearly), pay-as-you-go packs. Pass jobId for options to unlock that conversion.
wpconvert_checkout	A Stripe checkout link for the option you picked. Needs a signed-in account. You open and pay; the agent never pays.

Configure (Claude Code)

claude mcp add wpconvert --scope user -- npx -y @wpconvert/mcp

--scope user makes the server available in every project. Confirm with claude mcp list (wpconvert … ✔ Connected) or /mcp inside a session. Then ask the agent to convert a folder; it will offer a guest link or a sign-in link.

To use an existing API key instead, add it before the --, after the server name: claude mcp add wpconvert --scope user -e WPCONVERT_API_KEY=wpc_live_xxx -- npx -y @wpconvert/mcp (-e accepts several values, so put the name first).

Configure (Cursor / Claude Desktop)

{
  "mcpServers": {
    "wpconvert": {
      "command": "npx",
      "args": ["-y", "@wpconvert/mcp"]
    }
  }
}

Optional env: WPCONVERT_API_KEY (an existing key; it takes precedence over a key saved by sign-in) and WPCONVERT_API_BASE (a non-default API host, for testing).

Sign-in and guest sessions are saved in ~/.wpconvert/config.json (mode 0600), shared with the wpconvert CLI. Tool results never include the key, the guest token or the link's device code.

Typical agent flow

Quota-first (recommended):

1. wpconvert_quota → review capabilities (conversion mode, can_start, download availability) and recommended_next
2. wpconvert_convert_folder { "path": "./my-site", "type": "theme" } → jobId + idempotency_key + recommended_next
3. wpconvert_check_status { "jobId": "..." } (repeat until done; follow recommended_next — usually poll every ~15s)
4. When recommended_next.tool is wpconvert_download_result → download the theme .zip
5. When preview-only or download locked → wpconvert_create_preview for a WordPress Playground URL (no ZIP)

If conversion is blocked (can_start: false), wpconvert_convert_folder returns a structured denial before zipping or submitting. Call wpconvert_quota to review recommended_action.

No key yet (guest):

1. wpconvert_convert_folder → recommended_next: wpconvert_connect { "kind": "guest" }
2. wpconvert_connect { "kind": "guest" } → the agent shows you a link and code; you open it and confirm you're human
3. wpconvert_connect_status → connected, with free previews left
4. wpconvert_convert_folder, wpconvert_check_status, then wpconvert_create_preview to see it in WordPress Playground (guest uploads up to 50MB zipped; never retried automatically, since each upload uses a preview)

Buying (download a theme, or a plan):

1. wpconvert_plans { "jobId": "..." } → every option and price; the agent asks you which one
2. Not signed in? wpconvert_connect { "kind": "login" }, then wpconvert_connect_status, then wpconvert_plans again
3. wpconvert_checkout with your choice's checkout_arguments → a Stripe link you open and pay
4. wpconvert_check_status → once paid, recommended_next is wpconvert_download_result. Guest themes you buy move to your account.

Capabilities and structured responses

Tools return human-readable prose plus a trailing JSON block (same ok() / fail() pattern as before). Key fields:

Field	Where	Meaning
quota	wpconvert_quota	Full backend quota body (unknown future fields preserved)
summary	quota, denials	Projected can_start, mode, consumes, download_available
capabilities_available	quota	false on legacy backends without capabilities.conversion
recommended_next	all tools	{ tool, reason, retry_after_seconds? } — which MCP tool to call next
next_action	convert success	String (unchanged) — human guidance for agents
idempotency_key	convert	Omitted on preflight denial (no key generated)

Status recommended_next rules:

• queued, pipeline stages, or tool-layer processing → wpconvert_check_status (poll)
• done + downloadable → wpconvert_download_result
• done + preview-only / download locked → wpconvert_create_preview (never download); the reason names wpconvert_plans for unlocking
• done + guest (guest: true, remaining_previews) → wpconvert_create_preview, then wpconvert_plans to buy
• failed → wpconvert_explain_failure

Idempotency recovery

• Leave idempotency_key blank for a new intentional conversion.
• If a prior wpconvert_convert_folder call timed out or returned an ambiguous network error, retry with the exact idempotency_key from that call — do not omit it and do not invent a new one.
• Do not reuse a key for changed files, options, or a deliberate new conversion.
• Preflight runs after path/plan validation but before key generation (when omitted), ZIP build, and submit — so blocked accounts never upload.

Preview-only / download locked

Free developer previews and guest previews are preview-only (Playground, no ZIP download). When download_available is false or preview_only is true, status and download tools recommend wpconvert_create_preview, wpconvert_plans or wpconvert_quota — not download retry.

Dependency pin

This package pins [email protected] exactly for shared capability helpers (resolveConvertPreflight, quota formatters).