QuokkaPix MCP Runner

Remote MCP with local execution

Claude web and other cloud MCP clients can use the OAuth-protected remote endpoint while the existing npm adapter executes every image operation on this computer.

npx quokkapix-mcp bridge --input-root /path/to/input --output-root /path/to/output

Remote MCP: https://quokkapix.com/mcp

The mcp:tools scope permits read tools. Processing and staged unlocks also require bridge:execute. The --reset option revokes the previous device before pairing a replacement.

The control plane relays settings, relative file names, status and result metadata. It has no image upload endpoint and does not relay source or output image bytes.

Claude / Cursor / local MCP practical guide

Use this page when you want a desktop AI agent to process local image files with QuokkaPix. The MCP runner is a local stdio adapter: the MCP client starts quokkapix-mcp, the adapter opens QuokkaPix in a local browser, uploads files through the browser file input, applies a recipe or direct settings payload, downloads the result and writes quokkapix-result.json.

This is not a hosted image-processing API. Source images stay in the local browser workflow instead of being uploaded to a QuokkaPix processing server.

Windows fallback command

If a Windows MCP client cannot resolve npx directly, start it through cmd /c. Use this only when the simple npx command is not detected by the client.

{
  "mcpServers": {
    "quokkapix": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "quokkapix-mcp"
      ],
      "env": {
        "QUOKKAPIX_APP_URL": "https://quokkapix.com/#agent=1"
      }
    }
  }
}

Local MCP clients and LLM wrappers

Any MCP-compatible local client that can start a stdio server can use the same package. This includes desktop clients, editor agents, LM Studio or Ollama wrappers that expose MCP tools to a local model.

The important rule is the same everywhere: pass real local image file paths to the MCP tool call, not to the public website URL. QuokkaPix receives files only through the local browser file input opened by the runner.

First useful prompts

What to verify after the run

Free and paid agent runs

Single-image agent runs, single-image scenarios and agent batches up to 5 files are free. Agent batch or batch-scenario runs from 6 to 50 files use the x402 unlock flow. Clients should fetch live terms from /api/agent-payment/options before requesting a paid unlock.

When payment is needed, the agent obtains an unlockToken, sets it in QuokkaPix before processing, and the unlock is consumed only when a paid batch or batch scenario starts.

Troubleshooting

Security boundary

Use the official QuokkaPix URL or a trusted local development URL. Do not point the runner at an arbitrary third-party appUrl, because the adapter uploads local files into the browser page it opens. The public website does not receive local file paths, and the adapter does not turn QuokkaPix into a public server-side image API.

FAQ for agents and developers

What agents can do

• Run official recipes for Shopify, Amazon, Google Merchant, WebP compression, PDF export, metadata cleanup, social packs, avatar packs and watermark batches.
• Run direct custom settings with process_with_settings, using the same payload as window.QuokkaPixAgent.applySettings.
• Validate result manifests and get QA checks for formats, dimensions, size limits, output kind, required output names and ZIP contents.
• Read x402 payment options and verify unlock tokens for paid agent batch runs.
• Upload optional local asset files for logo watermarks and background-image replacement.

Current browser capabilities

• The optional capabilities.backends object reports planned processing, encoding and background-AI routes with explicit fallbacks. Existing MCP request and response fields are unchanged.
• Advanced export can use browser-loaded WASM encoders for JPEG, PNG optimization, WebP, AVIF and experimental JPEG XL when available.
• ZIP upload is batch-only: the browser unpacks supported images locally before the runner starts processing.
• PDF tools use tool=pdf in direct settings: split and extract use one uploaded PDF, merge uses a batch of PDFs, and images-to-PDF remains an image workflow. Extract preserves the page order from pdf-pages; use pdf-extract-output=zip for separate one-page PDFs.

What to check after a run

• Confirm that the output directory contains the generated image, ZIP or PDF plus quokkapix-result.json.
• Read qa.ok and qa.checks before accepting a marketplace or social-image batch.
• Keep source files separate because QuokkaPix writes delivery outputs, not replacement masters.
• For paid agent batches, fetch live payment options before requesting an x402 unlock token.

What makes a run acceptable

• The MCP client started the local stdio adapter and the adapter opened an expected QuokkaPix URL.
• Files entered through the browser file input, not through a public URL parameter.
• The manifest status is done, qa.ok is true when a recipe has QA, and warnings are reviewed before using the output.
• For paid batches, the unlock token is verified before start and consumed only by a paid run above the free small-batch limit.

MCP tools

• list_recipes
• get_recipe
• validate_recipe
• list_rule_profiles
• get_rule_profile
• validate_result_manifest
• process_images
• process_with_settings
• get_payment_options
• explain_payment_flow
• verify_unlock_token

Official recipes

Examples

{
  "settings": {
    "mode": "single",
    "tool": "compress",
    "settings": {
      "compress": {
        "format": "webp",
        "quality": 0.82
      }
    }
  },
  "inputFiles": [
    "/Users/me/photo.jpg"
  ],
  "outputDir": "/Users/me/quokkapix-output"
}

Important notes

Images still enter through the local browser file input. QuokkaPix does not expose a public server-side processing API.