runfra-mcp

Model Context Protocol (MCP) server for Runfra — async batch image generation for high-volume creative and ecommerce automation. Plug it into Claude Desktop, Cursor, or any MCP-aware host and the assistant can submit text-to-image jobs, image-to-image ("product scene") jobs, and poll for results inside a conversation.

Tools

The server exposes three tools. All use RUNFRA_API_KEY from the environment.

runfra_create_image_job

Submit a text-to-image job. Returns immediately with job_id + seeds; pair with runfra_get_job_result to fetch the final image URLs.

Argument	Default	Notes
prompt	required	1–2000 chars
model	stable-diffusion-xl-base-1.0	also flux-schnell, flux-dev
width / height	1024	512–1024
batch_size	1	1–100. Your account tier may cap the maximum batch size.
quality_mode	strict	strict / soft / off
negative_prompt	none	ignored by flux-schnell and flux-dev

runfra_get_job_result

Get the current state of any job by ID.

Argument	Default	Notes
job_id	required	UUID returned by either creation tool
wait_for_seconds	0	0 = single-shot. >0 = poll every 3 s up to that many seconds (hard-capped at 300). On timeout the tool returns the in-progress state with timeout_exceeded: true so the caller can retry.

runfra_create_product_scene

Image-to-image: take a public HTTPS image URL plus a scene prompt, return one restyled image. This tool currently submits SDXL img2img jobs; output is capped at 768×768 px. Combines two backend calls (/v1/uploads/input-image-by-url + /v1/jobs) into one tool.

Argument	Default	Notes
image_url	required	Public HTTPS URL. PNG / JPEG / WebP, ≤10 MB, longest side ≤1024 px. SSRF-guarded server-side fetch.
scene_prompt	required	1–2000 chars
width / height	512 / 512	384–768, multiples of 64; width × height ≤ 768×768
strength	0.6	0.4–0.9. Lower keeps the reference visible; higher re-imagines the frame
crop_anchor	center	also top / bottom / left / right / top-left / top-right / bottom-left / bottom-right
wait_for_seconds	90	poll for completion. 0 = fire-and-forget

Install

pip install runfra-mcp

Requires Python ≥3.10.

Configure your MCP client

Get an API key at runfra.com/dashboard/api-keys. The key is shown once at creation — save it immediately.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "runfra": {
      "command": "runfra-mcp",
      "env": {
        "RUNFRA_API_KEY": "rfa_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. The three tools appear under "Runfra" in the tool picker.

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "runfra": {
      "command": "runfra-mcp",
      "env": {
        "RUNFRA_API_KEY": "rfa_your_key_here"
      }
    }
  }
}

Restart Cursor.

Any other MCP host

Run the server directly:

RUNFRA_API_KEY=rfa_your_key_here runfra-mcp

It speaks MCP over stdio — no network port is opened.

Optional env vars

• RUNFRA_BASE_URL — override the API base URL. Default is https://api.runfra.com. Useful for staging environments.

Example session

You — "Generate me a photoreal red panda on a wooden bridge, golden-hour light. Wait for the result."

Claude uses runfra_create_image_job(prompt="a photoreal red panda...", batch_size=4), then immediately runfra_get_job_result(job_id=..., wait_for_seconds=120), and replies with the best_result_url.

You — "Now take this photo (https://cdn.example.com/lamp.jpg) and put it in a Mediterranean kitchen at golden hour."

Claude uses runfra_create_product_scene(image_url="https://cdn.example.com/lamp.jpg", scene_prompt="on a marble countertop in a Mediterranean kitchen, golden hour light", strength=0.55) and replies with the result URL.

Pricing

runfra-mcp itself is free. Image generation consumes Runfra credits; new accounts come with 100 credits.

Model	≤512 px	≤768 px	>768 px
SDXL	1 cr	2 cr	3 cr
FLUX Schnell	2 cr	3 cr	4 cr
RunFra Pro (flux-dev)	5 cr	9 cr	14 cr

Total cost = credits_per_image × batch_size. Platform failures and no-result jobs are refunded automatically. Best-effort delivery (no candidate cleared the quality gate) does not refund — the image is still delivered. See runfra.com/pricing for credit packs.

Security

• Treat your RUNFRA_API_KEY like a password. The MCP host process spawns this server with the key in its environment — anyone with read access to the host's config file can read the key.
• Revoke keys at runfra.com/dashboard/api-keys if a key is exposed.
• Reference image URLs must be public HTTPS. The Runfra API refuses http://, file://, data:, and any host that resolves to a private/ reserved IP range (RFC 1918, loopback, link-local incl. cloud metadata, CGNAT, IPv6 ULA / link-local).

Develop

git clone https://github.com/spencer9714/Runfra.git
cd Runfra/mcp-server
pip install -e .
RUNFRA_API_KEY=rfa_your_key_here runfra-mcp   # runs the server on stdio

License

MIT