WPConvert MCP

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. No API key is needed to try it: a quick browser check gives a few free guest previews, and browser sign-in creates a key for you. Downloading theme.zip requires Starter (one theme), PRO, Agency, or PAYG credits, which you can buy from the terminal or the agent.

Agent quickstart (MCP)

If you are a coding agent in Cursor, Claude Code, 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 (no key yet? wpconvert_connect)
3. wpconvert_convert_folder → wpconvert_check_status → wpconvert_download_result or wpconvert_create_preview
4. To download a preview or get a plan: wpconvert_plans → the user picks → wpconvert_checkout

Portable Skill: skills/wpconvert/SKILL.md

MCP setup (Cursor / Claude Code / Claude Desktop)

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

Claude Code — one command, no config file, no key:

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

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

Cursor / Claude Desktop:

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

Optional env: WPCONVERT_API_KEY to use an existing key (for Claude Code, add -e WPCONVERT_API_KEY=wpc_live_EXAMPLE_ONLY_NOT_A_REAL_KEY after --scope user), and WPCONVERT_API_BASE for 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
• Optional: a WPConvert API key (wpc_live_...) from your dashboard (Settings → API & CLI), or let wpconvert login / wpconvert_connect create one through browser sign-in
• Guest previews without an account: a few WordPress Playground previews for 24 hours after one browser check; buy one with Starter to download it
• 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.4.0

npm install -g wpconvert
# or: npx wpconvert
wpconvert convert .         # no key: offers free guest previews after a browser check
wpconvert login             # or sign in through your browser (saves a key)
wpconvert quota
wpconvert convert . --type theme
wpconvert plans             # what each option includes and costs
wpconvert unlock <jobId>    # buy this theme or a plan, then download it

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.

See docs/api.md, openapi.yaml, and examples/ for full examples.

Environment variables

See .env.example for a safe template with fake values.

Development

git clone https://github.com/FTWAgency/wpconvert-devtools.git
cd wpconvert-devtools
npm install
npm run check

License

MIT — Copyright (c) 2026 FTW Agency, operating WPConvert.ai. See LICENSE.

Security

See SECURITY.md for reporting vulnerabilities and upload safety guidance.

Contributing

See CONTRIBUTING.md.