Get API key
Connect an agent

Agent skill & CLI

A skill directory and a zero-dependency Node CLI that emits structured JSON, so a terminal or coding agent can generate, edit and process images by shelling out to one command.

Install

The skill ships as a directory containing SKILL.md, a reference guide and the CLI script. Add it with the skills installer:

terminal
npx skills add imagemcp/skill

Source lives in the skill repository if you would rather vendor it into your own agent setup.

Connect your account

The CLI resolves credentials in two ways. An environment variable is simplest for CI and scripted agents:

terminal
export IMAGEMCP_API_KEY="sk-img-gen-…"
export IMAGEMCP_API_URL="https://api.imagemcpserver.com"   # optional

Interactively, run the login flow instead — it opens a browser, lets you pick or create a key, and stores it under your home directory:

terminal
npx imagemcp login

Unauthenticated calls fail loudly

If no key is found the CLI says so rather than guessing, which is the behaviour agents should surface to the user instead of retrying.

Command reference

Every command prints JSON on stdout. The names line up one-to-one with the MCP tools and REST endpoints:

CommandMCP toolCreditsDoes
user:infoget_user_infoFreeRead the authenticated account's profile, plan and remaining credit balance.
models:listlist_modelsFreeList every live image model you can pass as the `model` parameter, with its credit cost.
generategenerate_imageModel costTurn a text prompt — optionally guided by reference images — into a hosted image.
generate_transparentgenerate_transparent_imageModel cost + 8Generate an image from a prompt and return it as a cut-out PNG with a transparent background.
editedit_imageModel costChange an existing image with natural-language instructions.
remove_bgremove_background8 creditsStrip the background from an image and return a transparent PNG.
upscaleupscale_image15 creditsIncrease an image's resolution while sharpening detail.
text_to_svgtext_to_svg5 creditsGenerate real vector SVG markup — icons, logos and marks — from a prompt.
compresscompress_image1 creditShrink an image's file size with quality control, and report exactly how much was saved.
convertconvert_format1 creditConvert an image between PNG, JPEG, WebP and other common formats.
multicallmulticallSum of the batchRun several image tools concurrently in a single request.
terminal
./scripts/imagemcp.js user:info

./scripts/imagemcp.js generate \
  --prompt "Paper-craft fox in tall grass, soft morning light" \
  --aspect-ratio "16:9" \
  --out ./fox.png

./scripts/imagemcp.js edit \
  --image ./fox.png \
  --prompt "Make it dusk, add fireflies" \
  --out ./fox-dusk.png

Common flags

  • --prompt — the instruction. Required by every generation command.
  • --image — input image for edit, remove_bg, upscale, compress and convert.
  • --ref — a reference image for generate; repeat the flag for several.
  • --out — write the result to a local file instead of printing the URL.
  • --model and --aspect-ratio — override the generation defaults.
  • --response-format b64_json — return base64 instead of a hosted URL.
  • --scale, --quality, --format — options for upscale, compress and convert.

Batching with multicall

When an agent needs several images in one turn, one multicall beats a loop of generate calls: the requests run concurrently and the credit total is settled once.

batch_requests.json
[
  { "tool": "generate_image", "args": { "prompt": "App hero image, 16:9", "aspectRatio": "16:9" } },
  { "tool": "generate_transparent_image", "args": { "prompt": "Mascot fox, isolated subject" } },
  { "tool": "text_to_svg", "args": { "prompt": "Minimalist lightning bolt icon" } }
]
terminal
./scripts/imagemcp.js multicall ./batch_requests.json

How agents should use it

The skill file ships with instructions for the agent itself. Two are worth knowing about because they change what a run costs:

  • Check user:info first. A run that starts without enough credits fails partway through, having already spent what it had.
  • Expand thin prompts before generating. "a logo" produces a generic result and a retry; a described logo usually lands first time.
  • Batch independent requests with multicall instead of issuing sequential generate calls.

Retries cost credits

Each regeneration is a fresh charge — credits are deducted before the model runs and failed calls are not refunded automatically. Prefer improving the prompt over retrying the same one.

FAQ

What is the difference between the skill and the MCP server?

They expose the same tools through different channels. The MCP server is for clients that speak the Model Context Protocol; the skill is for agents that can run shell commands — the CLI prints JSON they can parse directly.

Does the CLI need any dependencies?

No. It runs on Node.js 18 or newer with no packages to install.

Where is the API key stored?

Either in the IMAGEMCP_API_KEY environment variable, or in ~/.imagemcp/config.json after you run the login flow. The CLI resolves the environment variable first.