WPConvert Devtools

Open-source developer tools for turning AI-built websites into WordPress themes from your terminal, API, or AI assistant.

WPConvert does not modify your source project and does not require WordPress credentials. Output is either theme.zip (paid) or a WordPress Playground preview URL (~10 minutes).

The CLI and MCP server are open source. The WPConvert conversion engine runs on WPConvert.ai and requires an API key. Free verified accounts can create preview-only developer conversions; downloading theme.zip requires PRO, Agency, or PAYG credits.

Agent quickstart (MCP)

If you are a coding agent in Cursor, Claude Desktop, or another MCP host, use the MCP tools (do not shell out to the CLI in the same session).

1. Configure @wpconvert/mcp — see examples/mcp/ and docs/agents.md
2. wpconvert_quota — inspect capabilities before converting
3. wpconvert_convert_folder → wpconvert_check_status → wpconvert_download_result or wpconvert_create_preview

Portable Skill: skills/wpconvert/SKILL.md

MCP setup (Cursor / Claude Desktop)

Current release: @wpconvert/mcp@0.3.1 (npx -y @wpconvert/mcp uses npm latest; pin @0.3.1 for deterministic installs).

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

Optional: set WPCONVERT_API_BASE to point at a non-default API host (testing only).

See docs/mcp.md and docs/agents.md for the full agent workflow.

This repository contains the open-source WPConvert developer tools:

These tools are thin clients that call the hosted API over HTTPS.

What this repo is NOT

This repository does not include the WPConvert conversion engine, backend workers, AI prompts, parser/mapper logic, billing/quota logic, or theme generation system. Those run on WPConvert.ai servers.

Requirements

• Node.js >= 18
• A WPConvert API key (wpc_live_...) from your dashboard (Settings → API & CLI)
• PRO/Agency or PAYG credits for full conversions with theme.zip download
• Free verified accounts can run up to 3 lifetime preview-only developer conversions (Playground preview, no ZIP)
• CLI, API, and MCP use the same credits as dashboard conversions for paid exports (1 credit per successful conversion; failed conversions are refunded)

Free developer previews

Free verified WPConvert accounts can create up to 3 lifetime developer previews from the CLI, API, or MCP. Preview-only conversions generate a WordPress Playground preview, but theme ZIP downloads are locked. To download theme.zip, upgrade to PRO/Agency or add PAYG credits, then re-run the conversion.

• Preview-only jobs are never retroactively downloadable — upgrading does not unlock an old job; convert again after upgrading.
• On success, wpconvert convert automatically creates a Playground preview URL.
• Preview-only jobs auto-open your browser by default (the preview is the deliverable).
• Use --no-open in CI/headless, or --no-preview to skip Playground entirely.

Expected preview-only CLI output

wpconvert convert . --type theme

Scanning /path/to/project ...
Packaging zip ...
Zip built: 1.2 MB compressed.
Uploading (multipart) and starting conversion ...
✔ Conversion queued: abc123-def456
Free developer preview 1 of 3.
Download locked. Upgrade to PRO or add PAYG credits, then re-run this conversion to download theme.zip.
  … processing 42%
✔ Conversion complete.
Download locked. Upgrade to PRO or add PAYG credits, then re-run this conversion to download theme.zip.
Creating Playground preview ...
✔ Preview ready (WordPress Playground):
  https://playground.wordpress.net/...
  Link expires ... and is single-use limited.
  Opening in your default browser ...
Upgrade to Pro/Agency or buy PAYG credits, then re-run convert to download theme.zip.

Paid conversions (PRO/Agency/PAYG) download theme.zip automatically and print the preview URL without auto-opening unless you pass --open.

Quickstart (CLI)

Current release: wpconvert@0.3.1

npm install -g wpconvert
# or: npx wpconvert
wpconvert login
wpconvert quota
wpconvert convert . --type theme

The CLI smart-zips your folder, runs a capability preflight before upload, polls until done, then downloads theme.zip (paid) or opens a Playground preview (free preview-only).

Useful convert flags

wpconvert convert . --dry-run      # list what would upload; no upload, no credit
wpconvert convert . --no-download    # paid: skip auto-download on success
wpconvert convert . --open           # paid: auto-open Playground in browser
wpconvert convert . --no-open        # preview-only: don't auto-open browser (CI/headless)
wpconvert convert . --no-preview     # skip Playground preview entirely
wpconvert preview <jobId> --open     # open an existing job's preview later

Preview before uploading

wpconvert convert . --dry-run

--dry-run lists exactly what would be uploaded — no upload, no credit used.

Safety defaults

By default the CLI excludes:

• .env and secret files (*.pem, *.key, id_rsa*, .npmrc, .ssh/, credentials*.json, …)
• node_modules, .git, build output (dist/, build/, …)
• Your project's .gitignore patterns

Symlinks are never followed. Use --include-env only if you truly intend to upload secrets (not recommended).

Only upload projects you own or have permission to process through WPConvert.

Developer API (REST)

WPConvert offers three developer surfaces: REST API, CLI, and MCP. All call the same hosted API at https://api.wpconvert.ai.

openapi.yaml is a byte-identical mirror of the canonical WPConvert API contract maintained in the private application repository. Do not independently modify API behavior or schemas here. Contract changes originate with the production API and are mirrored into this repository.

Quick example:

curl https://api.wpconvert.ai/api/convert/quota \
  -H "X-API-Key: wpc_live_EXAMPLE_ONLY_NOT_A_REAL_KEY"

See docs/api.md for the full workflow (quota → convert → status → download or Playground) and examples/ for end-to-end scripts.

API overview (legacy quick reference)

Prefer docs/api.md and openapi.yaml for the current contract. The table below is a minimal quick reference.

All requests require the X-API-Key header. Base URL: https://api.wpconvert.ai

Start a conversion

curl -X POST https://api.wpconvert.ai/api/convert \
  -H "X-API-Key: wpc_live_EXAMPLE_ONLY_NOT_A_REAL_KEY" \
  -F "file=@my-site.zip" \
  -F "project_name=my-site" \
  -F "export_type=theme"

Returns { "jobId": "...", "status": "queued", ... }.

Check status

curl https://api.wpconvert.ai/api/convert/JOB_ID/status \
  -H "X-API-Key: wpc_live_EXAMPLE_ONLY_NOT_A_REAL_KEY"

Download result

curl https://api.wpconvert.ai/api/download/PROJECT_ID \
  -H "X-API-Key: wpc_live_EXAMPLE_ONLY_NOT_A_REAL_KEY"

Returns { "download_url": "https://...", "name": "my-site-theme.zip" }. Follow the download_url to fetch the theme zip — do not hard-code storage paths.

Read the full README on GitHub →