ImageStep — Claude Code MCP server: generate and edit images
An MCP server for image work: generation, transforms and presets. Images stay out of the context window — you get ids, paths and links back.
claude mcp add mcp -e IMAGESTEP_API_KEY=<IMAGESTEP_API_KEY> -- npx -y @imagestep/mcpWhat ImageStep does
ImageStep hands the agent a set of image tools. generate turns a prompt into images, transform runs a single operation, run_preset executes a saved multi-step preset, job_status reports progress, search_assets finds assets, and save_preset stores a chain under a name and version. A preset with subjects keeps one character or product consistent across a batch, and slug@version pins an exact version.
Image bytes never come back into context. A tool answers with an asset id, a path to a temp file, or a URL. transform has two modes and the input decides which one runs, not the agent. Synchronous mode needs exactly one local file or one URL, a deterministic op, and wait: true — nothing lands in the account. Everything else becomes a job with progress and cancellation. A local server returns path; the hosted endpoint at https://mcp.imagestep.dev/mcp returns a signed link with expiresInSeconds.
You need an IMAGESTEP_API_KEY. Paid tools accept dry_run, which quotes the exact price and creates nothing, so a bad parameter is refused before any credit is charged. Calling a write tool again with the same idempotency_key and the same arguments returns what the first call produced instead of submitting a second job.
What it helps with
- generate an image from a prompt and get a link to it
- run a batch of images through one preset while keeping a character consistent
- remove a background or upscale in a single operation
- render PNGs from a template and a set of items
- check the price of an operation before running it
Example prompts for the agent
- Generate three cover variants from this prompt and show me the URLs
- Run
hero.pngthroughremove_bgwithwait: true - Save this chain of steps as a preset and return the
slug@version
How to install ImageStep
1Platform CLI
claude mcp add mcp -e IMAGESTEP_API_KEY=<IMAGESTEP_API_KEY> -- npx -y @imagestep/mcpReplace <…> with your own values
2Platform CLI: remote server
claude mcp add --transport http mcp https://mcp.imagestep.dev/mcp1Platform CLI: remote server
codex mcp add mcp --url https://mcp.imagestep.dev/mcp2Platform CLI
codex mcp add mcp --env IMAGESTEP_API_KEY=<IMAGESTEP_API_KEY> -- npx -y @imagestep/mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"mcp": {
"url": "https://mcp.imagestep.dev/mcp"
}
}
}{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@imagestep/mcp"
],
"env": {
"IMAGESTEP_API_KEY": "<IMAGESTEP_API_KEY>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"mcp": {
"type": "http",
"url": "https://mcp.imagestep.dev/mcp"
}
}
}{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@imagestep/mcp"
],
"env": {
"IMAGESTEP_API_KEY": "<IMAGESTEP_API_KEY>"
}
}
}
}Replace <…> with your own values
1Platform CLI: remote server
gemini mcp add -t http mcp https://mcp.imagestep.dev/mcp2Platform CLI
gemini mcp add -e IMAGESTEP_API_KEY=<IMAGESTEP_API_KEY> mcp npx -y @imagestep/mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about ImageStep
How do I install ImageStep in Claude Code?
Over stdio: claude mcp add mcp -e IMAGESTEP_API_KEY=<IMAGESTEP_API_KEY> -- npx -y @imagestep/mcp. Or connect the hosted endpoint: claude mcp add --transport http mcp https://mcp.imagestep.dev/mcp.
What does ImageStep do?
It gives the agent tools for generating and editing images: presets, assets and jobs. Answers come back as asset ids and URLs rather than the images themselves.
How is synchronous transform different from a job?
Synchronous mode handles one local file or URL, a deterministic op and wait: true, and stores nothing in the account. Anything else — several images, asset_ids, an AI op, or wait: false — runs as a job with progress and cancellation.