image_studio_mcp

A Model Context Protocol server that lets any MCP client — Claude Code, opencode, Claude Desktop, or your own — generate and edit images in-loop with Image Studio. Results come back inline (the model sees the image) and each PNG is saved to disk.

You need nothing but Node ≥20 and an API key: point your client at npx @ross_technologies/image_studio_mcp, drop in your key, and go. No clone, no build, no local model — all rendering runs on the hosted Image Studio API.

• 📦 npm: @ross_technologies/image_studio_mcp · v1.0.1
• 🔑 Get an API key: https://studio.ross-developers.com
• 📖 Full docs: https://studio.ross-developers.com/agents/mcp/docs

Quick start

Add this to your MCP client config (e.g. .mcp.json), put in your key, and restart the client:

{
  "mcpServers": {
    "image-studio": {
      "command": "npx",
      "args": ["-y", "@ross_technologies/image_studio_mcp"],
      "env": { "IMAGE_STUDIO_API_KEY": "isk_your_key_here" }
    }
  }
}

Don't have a key yet? Use the watermarked, no-GPU sandbox key isk_test_onelove to try it out.

Then just ask your agent to make an image — e.g. "generate a sunset over Kingston harbour" — and it will call generate_image, show you the result inline, and save the PNG.

Tools

tool	description
list_models	list the image models (generation + editing) with their tasks and parameters
generate_image	text→image (irie, vibes, roots, sunsplash, criss, kaya, wagwan) — blocks, returns inline + saves
edit_image	image edit (remix, bashment, patchie[mask], bredda, rocksteady, biggup[upscale]) — input_image = path / data URI / base64
get_job	poll a job by id
cancel_job	cancel a job

generate_image / edit_image submit the job, poll to completion (up to MCP_MAX_WAIT_S), return every image as an inline base64 block and write it to IMAGE_OUTPUT_DIR/<job_id>/<n>.png. Call list_models first to see every model, its task, and its tunable parameters.

Configuration

Set via your MCP client's env block (above) or a .env file. See .env.example.

var	required	default	notes
IMAGE_STUDIO_API_KEY	✅	—	Your key from https://studio.ross-developers.com. Server refuses to start without it.
IMAGE_OUTPUT_DIR		<package>/outputs	where PNGs are saved
MCP_MAX_WAIT_S		900	max seconds a tool blocks before returning a job handle

Install (optional)

npx needs no install. To pin it globally instead:

npm install -g @ross_technologies/image_studio_mcp
# then use "command": "image_studio_mcp" (no npx) in your MCP config — the bin is unscoped

From GitHub Packages

Also mirrored to GitHub Packages under the @ross-sec scope. Point that scope at GitHub's registry, then install:

echo "@ross-sec:registry=https://npm.pkg.github.com" >> .npmrc
npm install @ross-sec/image_studio_mcp

Releases

• Latest: v1.0.1 — see CHANGELOG.md.
• npm: https://www.npmjs.com/package/@ross_technologies/image_studio_mcp
• GitHub Packages: https://github.com/ross-sec/image_studio_mcp/packages

How it works

generate_image / edit_image call your Image Studio backend, poll the job to completion, and return the finished PNG both inline (so the model sees it) and on disk. Nothing runs locally — the server is a thin, typed client over the hosted /v1 API. It talks to your MCP client over stdio, and logs only to stderr (stdout is the JSON-RPC stream). Your IMAGE_STUDIO_API_KEY is read from the client env / a local .env and is never written to disk or logged. See SECURITY.md.

Contributing & conduct

Contributions welcome — see CONTRIBUTING.md. This project follows the Contributor Covenant.

License

MIT © Andre Ross