@imagepipeline/mcp

Model Context Protocol (MCP) server for the ImagePipeline API. It exposes image generation, editing, try-on, background, branding, and upload as agent tools so an AI agent (Claude Desktop, Claude Code, or any MCP client) can call them directly.

Every tool blocks until the job is done and returns a small JSON payload — the result url, status, cost_usd, and a machine-readable error_code on failure — so the agent never has to write a polling loop.

Install

npm install -g @imagepipeline/mcp

Configure (Claude Desktop / Claude Code)

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "imagepipeline": {
      "command": "imagepipeline-mcp",
      "env": { "IMAGEPIPELINE_API_KEY": "ip_live_xxxxxxxxxxxx" }
    }
  }
}

Get a key at imagepipeline.io. The key starts with ip_live_.

Tools

| Tool | What it does | Notes | |------|--------------|-------| | generate_image | Text → image | No source image needed | | generate_video | Image → short video | Needs a public image URL | | generate_speech | Text → speech | Returns audio URL | | edit_image | Instruction-based edit | 1 URL, or 2 to combine; mask_segment for targeted edits | | segment_image | Detect editable regions | Read-only; run before targeted edit_image | | remove_background | Cutout / recolor | Returns cutout_url + optional composited url | | change_background | Swap background, keep subject | Provide subject_description | | upscale_image | Enhance / upscale | scale 1–4 | | stamp_logo | Overlay a logo | Fast compositing | | tryon | Virtual try-on | Person + clothing | | faceswap | Swap a face | Source + target | | upload_image | Local file → public URL | Use when you only have a local path | | get_account | Plan, balance, allowed ops | Preflight before expensive calls |

Typical agent flow

1. get_account → confirm the plan allows the operation and there's balance.
2. upload_image for any local files → get public URLs.
3. (optional) segment_image → discover a mask_segment label.
4. Run the operation (edit_image, tryon, …) → get url + cost_usd.

Errors

On failure a tool returns isError: true with:

{ "ok": false, "error": "…human message…", "error_code": "INSUFFICIENT_BALANCE", "retryable": false }

error_code is stable and machine-readable — branch on it. retryable tells the agent whether to back off and retry vs. fix the input.

Develop

npm install
npm run build
IMAGEPIPELINE_API_KEY=ip_live_xxx node dist/index.js

License

MIT